Java Bindings & Mapping

In this section:

• Java Bindings
• Mapping to Java

Java Bindings

The bindings specify what Java types have to be generated from the XML Schema.

The Java code generation can be done in webMethods Master Data Manager (see Developer Assistant  : Button "Generate Java") or with an Ant Script (see Using Ant).

Benefits

Ensuring the link between XML Schema structure and Java code provides a number of benefits:

• Development assistance:
  automatic completion when writing access path to parameters (if supported by your IDE) ;
• Access code verification  :
  all accesses to parameters are verified at code compilation ;
• Impact verification  :
  each modification of the adaptation model impacts the code compilation state ;
• Cross-references :
  by using the reference tools of your IDE, it is easy to verify where a parameter is used

Consequently, we strongly recommend to use Java code generation.

XML Declaration

The specification of the Java types to be generated from the XML schema is included in the main schema.

Each binding element defines a generation target. It must be located at xs:schema/xs:annotation/xs:appinfo/mdmbnd:binding (XPath notation) where the prefix mdmbnd is a reference to the naming space identified by the URI urn:mdm-schemas:binding_1.0. Several binding elements can be defined if you have different generation targets.

The attribute targetDirectory of the element mdmbnd:binding defines the root directory for Java types generation (generally, it is the directory of the project source codes "src"). A relative path is interpreted relatively to the current runtime directory of the VM (not relative to the XML schema).

See the bindings XML Schema.

Example

Thus, we can define java constants for XML schema paths. For that, we generate one or several interfaces from a schema node (that can be the root node "/"). Hence, in the previous example, we generate two interfaces of java paths constants, one from node "/rules" and the other from node "/stylesheet" of the considered schema. Interfaces names are described by the tags javaPathConstants with the attribute typeName and the associated node is described by the tag nodes with the attribute root.

Mapping to Java

XML Schema instantiation scenarios

An XML Schema element is instantiated into a Java object in the following cases:

1. If, in the XML Schema, the declaration of an element defines a default value, then, when the XML Schema is loaded in VM memory, this value is represented by a corresponding Java class instance
2. If a terminal adaptation node defines a value, then when the adaptation is loaded in VM memory, this value is represented by a corresponding Java class instance
3. When an instance of the class MDMContext is create, each node that has a value in the adaptation copies this value in the context.

Multi-occurrenced elements (maxOccurs > 1)

If the attribute maxOccurs is greater than 1, then the corresponding instance in Java is an instance of java.util.List.

Elements of the list are instances of the Java class deduced from the rules below.

Simple types

Each XML Schema simple type corresponds to a Java class.

If the attribute maxOccurs is greater than 1, then the corresponding instance in Java is an instance of java.util.List. Elements of the list are instances of the Java class in the table.

Complex types

By default, a complex type is instantiated with an webMethods MDM internal class. This class provides a generic implementation, light and optimized.

JavaBeans

It is also possible to instantiate a specific Java class when instantiating a complex type. This is achieved by adding the attribute mdm:class in the complex node definition. It is also required to specify the attribute mdm:access (see example), so that the node is considered as terminal, unless the element has xs:maxOccurs > 1 (because in this later case it is already considered as terminal).

The Java class must conform to the JavaBean protocol. This means that each child of the complex type must correspond to a JavaBean property of the class. If the JavaBean property has access restriction (read-only, write-only), then the child must define the same restriction of each access property.

Example :

In this example , the class Java com.carRental.Customer must define the methods getFirstName() and setFirstName(String).

A JavaBean may have a specific user interface within webMethods Master Data Manager. This is achieved using a com.softwareag.mdm.ui.UIBeanEditor.

Java Bindings & Mapping

Dans cette section:

• Java Bindings
• Mapping to Java

Java Bindings

Les bindings du modèle d'adaptation spécifient quels sont les types Java à générer à partir du schéma XML.

La génération proprement dite du code Java peut être effectuée via webMethods Master Data Manager (voir Assistant développeur : Bouton "Générer Java") ou via un script Ant (voir Utilisation de Ant).

Avantages

Le fait d'assurer un lien entre la structure du schéma XML et le code Java apporte de nombreux avantages :

• Assistance au développement :
  complétion automatique lors de l'écriture de chemins d'accès à des paramètres (dans la mesure où l'environnement de développement le supporte) ;
• Vérification du code d'appel :
  l'ensemble des appels aux paramètres d'adaptation sont vérifiés dès la compilation du code ;
• Mesure d'impact :
  toute modification du modèle d'adaptation impacte immédiatement l'état de compilation du code ;
• Référencement :
  en utilisant l'outil de référencement de l'environnement de développement, il est facile de lister où est utilisé un paramètre donné.

En conséquence, il est fortement recommandé d'utiliser la génération des interfaces Java.

Déclaration XML

La spécification des types Java à générer à partir du schéma XML est incluse directement dans le schéma XML principal du modèle d'adaptation.

Chaque élément binding définit une cible de génération. Il doit être situé à l'emplacement xs:schema/xs:annotation/xs:appinfo/mdmbnd:binding (notation XPath) où le préfixe mdmbnd fait référence à l'espace de nommage identifié par l'URI urn:mdm-schemas:binding_1.0. Plusieurs éléments binding peuvent être définis s'il y a des cibles de génération distinctes.

L'attribut targetDirectory de l'élément mdmbnd:binding définit le répertoire racine de génération des types Java (généralement, il s'agit du répertoire des codes sources "src" du projet). Un chemin relatif est interprété relativement au répertoire courant d'exécution de la VM (et non par rapport à la localisation du schéma).

Consultez les bindings XML Schema.

Exemple :

Ainsi, on va pouvoir associer des constantes java aux chemins d'un schéma XML. Pour cela, on génère une ou plusieurs interfaces à partir d'un noeud du schéma (pouvant être le noeud racine "/"). Dans l'exemple précédent, on va générer deux interfaces de constantes java, l'une à partir du noeud "/rules" et l'autre à partir du noeud "/stylesheet" du schéma considéré. Les noms d'interfaces sont décrits dans les balises javaPathConstants avec l'attribut typeName et le noeud associé est décrit dans la balise nodes avec l'attribut root.

Mapping vers Java

Scénarios d'instanciation d'un type XML Schema

Un type XML Schema est instancié en une classe Java dans les cas suivants :

• Si, dans le schéma XML, la déclaration d’un élément définit une valeur par défaut alors, quand le schéma XML est chargé dans la mémoire de la VM, cette valeur est représentée par une instance de la classe Java correspondante.
• Si un noeud terminal d’adaptation définit une valeur, alors quand l’adaptation est chargée dans la mémoire de la VM, cette valeur est représentée par une instance de la classe Java correspondante.

Cas des éléments multi-occurrencés (maxOccurs > 1)

Si l’attribut maxOccurs est strictement supérieur à 1, alors l’instance correspondante sous Java est une instance de java.util.List.

Les éléments de la liste sont alors des instances de la classe Java déduite des règles ci-dessous.

Cas des types simples

Chaque type simple XML Schema prédéfini par webMethods MDM correspond à une classe Java.

Cas par défaut des types complexes

Par défaut, un type complexe est instancié au moyen d’une classe interne MDM. Cette classe fournit une implémentation générique, légère et optimisée.

Cas des JavaBeans

Il est possible d’instancier une classe Java particulière lors de l’instanciation d’un type complexe. Ceci se fait par l’ajout de l’attribut mdm:class dans la définition du noeud complexe. Il sera aussi nécessaire de définir l'attribut mdm:access (voir exemple), de telle sorte que le noeud soit considéré comme terminal, sauf si l'élément a xs:maxOccurs > 1 (puisque dans ce cas il est déjà considéré comme terminal).

La classe Java spécifiée par mdm:class doit être conforme au protocole JavaBean, c’est à dire que chaque fils du type complexe doit correspondre à une propriété JavaBean de la classe. Si la propriété JavaBean a des restrictions d’accès (lecture-seule, ou écriture-seule), alors le fils correspondant doit définir la même restriction sur les caractéristiques d’accès.

Exemple :

Dans cet exemple, la classe Java com.carRental.Customer doit définir les méthodes getFirstName() et setFirstName(String).

Un JavaBean peut disposer d'une interface utilisateur spécifique dans webMethods Master Data Manager en implémentant un com.softwareag.mdm.ui.UIBeanEditor.