Home > Tutorial

Design an Adaptation Model

The adaptation model used by EBX.Platform adopts a standard file format, widely accepted in the market as XML Schema.

The purpose of an XML Schema is to define the legal building blocks of an XML document. This XML document contains the Master Data to be managed by EBX.Platform.

In the following chapters, we will, step by step, describe the creation of an XML Schema model, corresponding to the publications database.

Schema skeleton

The simplest version of a Schema used by EBX.Platform is described here:

<?xml version="1.0" encoding="UTF-8"?>

<!---->

<!--   Copyright © Orchestra Networks 2000-2006. All rights reserved. --> 

<!---->

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 

xmlns:osd="urn:ebx-schemas:common_1.0" xmlns:fmt="urn:ebx-schemas:format_1.0" 

xmlns:ebxbnd="urn:ebx-schemas:binding_1.0"> 

    <xs:import namespace="urn:ebx-schemas:common_1.0" 

schemaLocation="http://schema.orchestranetworks.com/common_1.0.xsd"/> 

    <xs:element name="root" osd:access="--"> 

    </xs:element>

</xs:schema>

All useful namespaces are declared at the beginning of the document,
A single element is declared as the root of the model (called ‘root’ in our example). This element has an attribute osd:access that specifies the access rights for this node. These rights may be set to nothing ("--").

See also:

Reusable types

For each table defined in the database, we will create an element type that can be reused across the Schema. This also simplifies the document structure.

Let’s start with the Publisher table. This table is defined as a complex type that describes a sequence of elements which are the original table fields:

pub_id, which is a mandatory 4-character string type element and follows a specific pattern
name, which is a mandatory 40-character string type element
city, which is an optional 20-character string type element

The corresponding complex type, named Publisher, may be defined as:

<xs:complexType name="Publisher"> 

        <xs:sequence> 

            <xs:element name="pub_id"> 

                <xs:simpleType> 

                    <xs:restriction base="xs:string"> 

                        <xs:maxLength value="4"/> 

                        <xs:pattern value="[0-9]{4}"/> 

                    </xs:restriction> 

                </xs:simpleType> 

            </xs:element> 

            <xs:element name="name"> 

                <xs:simpleType> 

                    <xs:restriction base="xs:string"> 

                        <xs:maxLength value="40"/> 

                    </xs:restriction> 

                </xs:simpleType> 

            </xs:element> 

            <xs:element name="city" minOccurs="0"> 

                <xs:simpleType> 

                    <xs:restriction base="xs:string"> 

                        <xs:maxLength value="20"/> 

                    </xs:restriction> 

                </xs:simpleType> 

            </xs:element> 

        </xs:sequence> 

</xs:complexType>

Please note that:

all standard field types are supported in XML schema. Hence any type defined in a database, whoever the vendor is, is supported in the target model,
any optional element is declared with the minOccurs="0" attribute,
any pattern may be specified using the xs:pattern element

See also:

EBX.Platform data types

Root element

Let’s now enrich the root element with a child node called Publishers, which defines the table records ( minOccurs="0" maxOccurs="unbounded" ) and is of the previously created 'Publisher' named type.

<?xml version="1.0" encoding="UTF-8"?>

<!---->

<!--   Copyright © Orchestra Networks 2000-2006. All rights reserved. --> 

<!---->

<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" 

xmlns:osd="urn:ebx-schemas:common_1.0" xmlns:fmt="urn:ebx-schemas:format_1.0" 

xmlns:ebxbnd="urn:ebx-schemas:binding_1.0"> 

    <xs:import namespace="urn:ebx-schemas:common_1.0" 

schemaLocation="http://schema.orchestranetworks.com/common_1.0.xsd"/> 

    <xs:element name="root" osd:access="--"> 

        <xs:complexType> 

            <xs:sequence> 

                <xs:element name="Publishers" type="Publisher" minOccurs="0" maxOccurs="unbounded"/> 

            </xs:sequence> 

        </xs:complexType> 

    </xs:element>

     <xs:complexType name="Publisher"> 

        <xs:sequence> 

            <xs:element name="pub_id"> 

                <xs:simpleType> 

                    <xs:restriction base="xs:string"> 

                        <xs:maxLength value="4"/> 

                        <xs:pattern value="[0-9]{4}"/> 

                    </xs:restriction> 

                </xs:simpleType> 

            </xs:element> 

            <xs:element name="name"> 

                <xs:simpleType> 

                    <xs:restriction base="xs:string"> 

                        <xs:maxLength value="40"/> 

                    </xs:restriction> 

                </xs:simpleType> 

            </xs:element> 

            <xs:element name="city" minOccurs="0"> 

                <xs:simpleType> 

                    <xs:restriction base="xs:string"> 

                        <xs:maxLength value="20"/> 

                    </xs:restriction> 

                </xs:simpleType> 

            </xs:element> 

        </xs:sequence> 

    </xs:complexType>

</xs:schema>

Intermediary schema

The same modelling process can be pushed further to define the other tables and related complex named types.

Please note that in the Titles table, only specific values are allowed for field named type. This can be implemented using the XML Schema enumeration declaration:

<xs:element name="type" default="Unknown">

    <xs:simpleType>

        <xs:restriction base="xs:string"> 

            <xs:maxLength value="30"/> 

            <xs:enumeration value="Business &amp; Technology"/> 

            <xs:enumeration value="Arts &amp; Entertainment"/> 

            <xs:enumeration value="Fiction"/> 

            <xs:enumeration value="Health &amp; Spirituality"/> 

            <xs:enumeration value="Lifestyle, Family &amp; Home"/> 

            <xs:enumeration value="Non fiction"/> 

            <xs:enumeration value="Recreation"/> 

            <xs:enumeration value="Unknown"/> 

        </xs:restriction> 

    </xs:simpleType>

</xs:element>

Please note that:

the ‘&’ symbol is not permitted in XML Schema document as it is internally used for other purposes. It may be changed to ‘&’ to prevent a syntax error.
the default value is specified using the 'default' attribute
among an enumeration, an allowable attribute is value (which specifies the value that is suggested to the EBX.Manager user), but attribute id may also be used, hence allowing to persist an integer value corresponding to the user choice, which significatively reduces the amount of data stored in the Master Data repository. If no id attribute is specified, the value attribute will be persisted instead.

The intermediary XML Schema for our Publications sample database is available here.

Important note:

As of now, each time the schema is updated with new features described in the following chapter, you have to refresh the model to take into account the amendments made in EBX.Manager (‘Refresh model’ link at the top of the user screen in development mode).

We just went through the definition of every element corresponding to each table in the database. Our modelling task is not over at this point, as we need to enrich the model with specific functionalities that XML Schema does not natively support.

EBX.Platform Module

Before going further in the design, let’s take some time to introduce the concept of modules in EBX.

An EBX.Platform Module allows the packaging of an adaptation model with additional resources (default message files, default formats, included XML Schemas, etc..)

On a J2EE application server, an EBX.Platform Module is integrated into a Web application. This provides Web applications features such as: class-loading isolation, WAR or EAR packaging, static Web resources exposition, hot-redeployment. In addition, if your user application is a Web application, it is possible to merge the EBX.Platform module with your application, in order to simplify deployment.

In our example, we will create a ‘ books ’ module packaging all necessary resources for the correct execution. The module structure looks like the following:

/WEB-INF/ebx/

This directory contains all description and configuration files for using EBX.Platform.
/WEB-INF/ebx/module.xml

This file defines the global properties of the EBX.Platform module:

<?xml version="1.0" encoding="UTF-8"?>
<module xmlns="urn:ebx-schemas:module_2.1" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="urn:ebx-schemas:module_2.1 http://schema.orchestranetworks.com/module_2.1.xsd">
    <name>Book Publishers</name>
    <publicPath>pubs</publicPath>
    <locales>
        <locale isDefault="true">en_US</locale>
        <locale>fr-FR</locale>
    </locales>
</module>

/WEB-INF/ebx/schema/pubs.xsd

This file defines the adaptation model (XML Schema document) of the EBX.Platform tutorial module. It contains all the model definitions we created so far.
/WEB-INF/web.xml

This file ensures module registration at application server launch:

<? xml version =" 1.0 " encoding =" UTF-8 " ?>
< !DOCTYPE web-app PUBLIC " -//Sun Microsystems, Inc.//DTD Web Application 2.3//EN "
  " http://java.sun.com/dtd/web-app_2_3.dtd " >
< web-app >
     < servlet >
         < servlet-name > BooksPublishersModule < / servlet-name >
         < description >
            This servlet is used for registering this web application as an EBX.Platform module.
            In its init() method, it must call " ModulesRegister.registerWebApp() ".
            You may create a dedicated servlet like here, or reuse an existing servlet.
         < / description >
         < servlet-class > com.orchestranetworks.tutorial.module.RegisterServlet < / servlet-class >
         < !--
            load-on-startup is required for the EBX.Platform registration to be done
            even without having started this web application (it is necessary
            if EBX.Manager is used before an application using adaptations is called).
          -- >
         < load-on-startup > 1 < / load-on-startup >
     < / servlet >
< / web-app >

/www/

This directory contains all external resources (accessible by URL). This directory is optional, localized and structured by resource type (html, images, jscripts, stylesheet). External resources in this directory can be referenced in adaptation models (parameters of type resource).

Once the structure is created, we need to register the module within EBX.Platform. For that purpose, we implement a specific Java class we call RegisterServlet in our example. This class is referenced in /WEB-INF/web.xml under the < servlet-class> element.

/*
* Copyright © Orchestra Networks 2000-2007. All rights reserved.
*/
package com.orchestranetworks.tutorial.module;

import javax.servlet.*;
import javax.servlet.http.*;

import com.onwbp. base .repository.*;

public class RegisterServlet extends HttpServlet
{
     public void init(ServletConfig config) throws ServletException
    {
        super.init(config);
        ModulesRegister.registerWebApp( this , config);
    }
     public void destroy()
    {
        ModulesRegister.unregisterWebApp( this , this .getServletConfig());
    }
}

As you can see, the only purpose of this class is to register/unregister a new servlet inside the application server. This way, our new module is known by EBX.Platform and will be managed accordingly.

Specify Tables

So far, we have not specified anywhere in our schema that the elements are of table type. This can be done using Table declarations.

In order to declare the primary keys of a table, EBX.Platform uses the primaryKeys element under an xs:annotation/xs:appinfo/osd:table element. We can define as many key fields as needed in this element, using a space character between them. Each field specified refers to one or more of the table elements using its path.

Example: Define pub_id as the primary key of table Publishers. We also define a custom localized label for presenting each record inside the table.

We declare the primaryKeys element under the Publisher complexType.

<xs:complexType name="Publisher"> 

    <xs:annotation> 

        <xs:appinfo> 

            <osd:table> 

                <primaryKeys>/pub_id</primaryKeys> 

                <defaultlabel xml:lang="en-US">Publisher's
name: ${name}</defaultLabel>

                <defaultLabel xml:lang="fr-FR">Nom
de l'éditeur : ${name}</defaultLabel>

            </osd:table>

        </xs:appinfo> 

    </xs:annotation>

    <xs:sequence>

        <xs:element name="pub_id"> 

            <xs:simpleType> 

                <xs:restriction base="xs:string"> 

                    <xs:maxLength value="4"/> 

                    <xs:pattern value="[0-9]{4}"/> 

                </xs:restriction> 

            </xs:simpleType> 

        </xs:element> 

        <xs:element name="name"> 

            <xs:simpleType> 

                <xs:restriction base="xs:string"> 

                    <xs:maxLength value="40"/> 

                </xs:restriction> 

            </xs:simpleType> 

        </xs:element> 

        <xs:element name="city" minOccurs="0"> 

            <xs:simpleType> 

                <xs:restriction base="xs:string"> 

                    <xs:maxLength value="20"/> 

                </xs:restriction> 

            </xs:simpleType> 

        </xs:element> 

    </xs:sequence>

</xs:complexType>

Once all complex types are correctly amended with the correct primary keys in the Schema, EBX.Platform will ensure that no identical records are created.

Moreover, in the case where a table field refers to another field in a different table, foreign keys ensure that data integrity is respected, preventing the selection of a value not defined in the range of the allowable values.

Foreign key definition is described in the following section.

See also:

Tables definition

Presentation informations

As you know, the user interface in EBX.Manager is dynamically generated from the XML Schema and may be localized in a multilingual environment.

For this purpose, every single element in the schema must be declared with all localization information. This way, all language-dependant presentation is packaged in the schema and will be used by EBX.Manager to render the information with the correct translation, depending on the user language preference.

An element may be declared with all translation information sitting under its xs:annotation/xs:documentation element.

The documentation element accepts the attribute xml:lang that specifies the language in which the information is translated.

All localization languages are defined in common_1.0.xsd schema.

Label and description

The label displayed by EBX.Manager for a given schema element is specified by an osd:label element. This label will be used for the column name in the table.

An osd:description element may also be specified and rendered in the information part of the EBX.Manager user interface (displayed after a click on the icon).

Example: Localize label and description elements for field name in table Publishers.

All elements in our sample database may be localized both in English ( xml:lang="en-US" ) and French ( xml:lang="fr-FR" .

<xs:element name="name">

    <xs:annotation> 

        <xs:documentation xml:lang="fr-FR"> 

            <osd:label>Nom</osd:label> 

            <osd:description>Nom de l'éditeur</osd:description> 

        </xs:documentation> 

        <xs:documentation xml:lang="en-US"> 

            <osd:label>Name</osd:label> 

            <osd:description>Publisher name</osd:description> 

        </xs:documentation> 

    </xs:annotation>

    <xs:simpleType>

        <xs:restriction base="xs:string"> 

            <xs:maxLength value="40"/> 

        </xs:restriction> 

    </xs:simpleType>

</xs:element>

And the following rendering in the French locale:

And in the English locale:

See also:

Labels and messages

Next: Define Advanced Constraints >

Home > Tutorial

Copyright © Orchestra Networks 2000-2010. All rights reserved.
Trademarks and brand names referred to in this web site relating to organizations
other than Orchestra Networks are the property of those organizations
and Orchestra Networks makes no claims to such property.