Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved


Chapter 6 Metadata : Guidelines for Metadata Use

Guidelines for Metadata Use
This section gives guidelines for metadata use.
Adapter Metadata Look-up
When configuring an adapter in TIBCO Designer, you specify metadata that restrict how the data an endpoint receives or sends should be structured.
When saving the TIBCO Designer project, the metadata are stored in the project repository. The SDK parses the metadata and creates instances of the metadata classes. These instances encapsulate the metadata information stored in TIBCO Administrator. The custom adapter can access the information through MClassRegistry and use it to process the available data.
Using TIBCO Designer, you can specify when the objects encapsulating the metadata should be created:
Specify one or more loadURL resources so that only frequently used classes are loaded upon start-up. Multiple project repository URLs can be specified from which metadata are loaded upon startup using the loadURL resources inside the Metadata URLs folder inside the adapter’s Advanced folder.
Only the metadata defined in the loadURL resource is loaded at start-up. If no loadURL resources are defined, nothing is loaded at start-up. Metadata that is not specified in the loadURL resource will be fetched on first access and will be cached for subsequent access.
Specify project repository URLs in which the custom adapter will search for a metadata object or attribute if its description is not yet loaded. Use the Metadata Search URL field in the Startup field of the adapter configuration object.
How the SDK Performs Metadata Look-up
When executing the MApp start() method, the Adapter SDK loads the metadata as follows:
The Adapter SDK first prepends the Metadata loadURL to form a full name (defined under the genericAdapter/Advanced/Metadata URLs/ folder). The Metadata loadURL specifies all the schema class definition that are to be pre-loaded on initialization and cached.
If the Metadata loadURL is not found, the Adapter SDK loads class definition from the repository using the searchURL (this is known as a lazy fetch).
The SDK checks the URL listed under the Metadata Search URL only when the class description cannot be located in the class registry using Full Name with the prepended Metadata load URL. For example:
Metadata Search URL= /tibco/public/class/ae/myfolder
Metadata load URL ("Metadata URLs" folder) = /tibco/public/class/ae
Short Name = GreetingClass
The full name used by the SDK to locate the class description will first be
/tibco/public/class/ae/GreetingClass
If the class description is not found there, SDK will use
/tibco/public/class/ae/myfolder/GreetingClass
Restrictions on Metadata
Be aware of the following restrictions on metadata:
Inner classes may be unions, sequences, or scalars. While it is possible to create and use messages with a top level class of sequence or union, these top-level classes can be difficult to use in conjunction with mappers.
The ActiveEnterprise schema type any is not a class type but an ActiveEnterprise scalar type. Type any should not be used in the context of the any class in a top level schema.
The dot character has special meaning in different places (such as subject name where it is used as element separator). Some adapters may decide to use a class name in their subject space, which can cause unpredictable issues.
Schema class names cannot have parentheses '(' ')' because they are used to distinguish script functions. The '^' is used by TIBCO Adapter SDK to delimit ActiveEnterprise wire format control fields and should not be used in class names. Below are legal non-alphanumeric characters; use them only if it is not possible to implement the adapter using alpha-numerics:
'_', ,'%','@', '|', '~', '{', '}', '#','-','$'
Schema class names and attribute names can only be in ASCII alphanumeric characters (only schema attribute values support Unicode).
Avoid the use of the sequence[any] data type where elements may have different classes (a heterogeneous list) because not all adapters are able to handle such list types.
Do not define and use an Operation class schema that uses inheritance. The ActiveEnterprise metadata model does not implement features such as C++ class method override and virtual methods.
Earlier versions of Adapter SDK allow to create schema that contained both simple value attributes and operation methods. Such schema are not supported in TIBCO Designer, which can read but cannot create class schema with both value attributes and operation methods. You must create separate classes for attributes and operations. This is enforced by TIBCO Designer.
A superclass and its child classes cannot have duplicate attribute names. If a child class and its parent class have duplicate attributes, a duplicate attribute exception will be thrown.
If a long class name (/tibco/public/class/ae/className) is specified without specifying a loadURL to access the class, and the repository file is very large and accessed remotely, an MConstructionException is thrown noting that the metadata class is not found.
Working with XML and XSD
Adapter SDK supports AESchema XSD (generic XSD is not supported). AESchema XSD support is defined as the conversion of MInstance to and from XML. In other words, Adapter SDK can only deserialize from an AESchema based XML data into an MInstance. Conversely, Adapter SDK can only serialize MInstance into AESchema based XML data.
If you have XML data from a third party application and want that data to be part of a TIBCO application, the XML data must conform to an AESchema XSD.
Because third party XML can, probably, not be created conforming to AESchema XSD, you must transform the third party XML using either BusinessWorks or a transformation plug-in. A transformation XSLT (mapping) can be generated using an AESchema XSD generated from the schema classes defined in Designer together with the XSD of the third party XML. For more information on the transformation plug-in, refer to Transformation Plug-in. You can always bypass any Adapter SDK supported ways of handling serialization and deserialization yourself. However, that is outside the scope of this guide.
Figure 18 shows where you can access an XSD from an AESchema defined class. You may want to use this XSD in an external modeling tool.
Figure 18 Access an XSD from an AESchema Defined Class
You can access the XML/XSD as follows:
1.
2.
Use the Tools > Export As XML Schemas menu command in TIBCO Designer. See the TIBCO Designer User’s Guide for details.
Use the ae2xsd utility to export an XSD. The utility is documented in the TIBCO Runtime Agent Administrator’s Guide.
3.
Use the following programming tools to get the XML and XSD from an application. These APIs allow you to access the XML and XSD needed for transformation or manipulation. It is useful when you want to transform non AESchema XSD based XML into SDK’s AESchema based XML (AEXML).
Get the AESchema XSD from the Adapter SDK class registry with MClassRegistry::getXSD(aeSchemaClassName).
SDK parses the incoming AESchema XML. The XSD from MClassRegistry::getXSD(aeSchemaClassName) validates the AEXML data instance.
Get the XML string message using MInstance::toXML() which gives the XML serialized form of MInstance (or use MTree::getTextBody() if you are accessing MTree).
 
By default, MAppProperties is configured with XSDGENERATION set to OFF. So, by default, the XSD is not used while parsing the AEXML. If you configure MAppProperties with XSDGENERATIONON set to ON, Adapter SDK can parse an incoming XML message using the XSD for the given class.
The getXSD() method is used to access the automatically generated XSD and is automatically used in the validation process. After XSDGENERATION is set to ON, you need not explicitly call getXSD() to do the validation.

Copyright © TIBCO Software Inc. All Rights Reserved
Copyright © TIBCO Software Inc. All Rights Reserved