Enterprise Metadata Discovery Specificationpublic.dhe.ibm.com/software/dw/library/j-emd/EnterpriseMetadata... · To enable resource adapters to provide this capability there needs

Enterprise Metadata Discovery Specification

Page 1 of 114

Enterprise Metadata Discovery IBM Corp. and BEA Systems, Inc. Version 1.0 June 2005 Authors Chinnappa Codanda, BEA Systems, Inc. Hesham Fahmy, IBM Corporation John Green, IBM Corporation Piotr Przybylski, IBM Corporation Mitch Upton, BEA Systems, Inc. Copyright Notice © Copyright BEA Systems, Inc. and International Business Machines Corp 2005. All rights reserved. License The Enterprise Metadata Discovery Specification is being provided by the copyright holders under the following license. By using and/or copying this work, you agree that you have read, understood and will comply with the following terms and conditions: Permission to copy and display the Enterprise Metadata Discovery Specification and/or portions thereof, without modification, in any medium without fee or royalty is hereby granted, provided that you include the following on ALL copies of the Enterprise Metadata Discovery Specification, or portions thereof, that you make: 1. A link or URL to the Enterprise Metadata Discovery Specification at this location: http://dev2dev.bea.com/wlplatform/commonj/emd.htmlor at this location: http://www.ibm.com/developerworks/library/specification/j-emd/ 2. The full text of this copyright notice as shown in the Enterprise Metadata Discovery Specification. IBM and BEA (collectively, the “Authors”) agree to grant you a royalty-free license, under reasonable, non-discriminatory terms and conditions to patents that they deem necessary to implement the Enterprise Metadata Discovery Specification. THE ENTERPRISE METADATA DISCOVERY SPECIFICATION IS PROVIDED "AS IS," AND THE AUTHORS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, REGARDING THIS SPECIFICATION AND THE IMPLEMENTATION OF ITS CONTENTS, INCLUDING, BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT OR TITLE. THE AUTHORS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF OR RELATING TO ANY USE OR DISTRIBUTION OF THE Enterprise Metadata Discovery SPECIFICATION. The name and trademarks of the Authors may NOT be used in any manner, including advertising or publicity pertaining to the Enterprise Metadata Discovery Specification or its contents without specific, written prior permission. Title to copyright in the Enterprise Metadata Discovery Specification will at all times remain with the Authors. No other rights are granted by implication, estoppel or otherwise.

Status of this Document This specification may change before final release and you are cautioned against relying on the content of this specification. IBM and BEA are currently soliciting your contributions and suggestions. Licenses are available for the purposes of feedback and (optionally) for implementation.

http://dev2dev.bea.com/wlplatform/commonj/emd.html

http://www.ibm.com/developerworks/library/specification/j-emd/


Page 2 of 114

Table of Contents 1. Introduction ...................................................................................................................5

1.1. Overview........................................................................................................................................5 1.2. Scope..............................................................................................................................................5 1.3. Target audience ..............................................................................................................................6 1.4. Organization...................................................................................................................................6 1.5. Document conventions...................................................................................................................6

2. Overview.........................................................................................................................7 2.1. Terms and Definitions....................................................................................................................7 2.2. Rationale ........................................................................................................................................8 2.3. Goal ................................................................................................................................................8

3. Architecture .................................................................................................................10 3.1. Internationalization ......................................................................................................................11

3.1.1. Data Transformation ........................................................................................................... 12 4. Roles/Scenarios ............................................................................................................14

4.1. Roles.............................................................................................................................................14 4.1.1. Business Analyst ................................................................................................................. 14 4.1.2. Developer ............................................................................................................................ 14 4.1.3. Administrator ...................................................................................................................... 14

4.2. Creating a Service ........................................................................................................................15 4.3. Editing connection information ...................................................................................................16 4.4. Sample Enterprise Application ....................................................................................................17

5. Connections ..................................................................................................................18 5.1. Connection Type ..........................................................................................................................18

5.1.1. Representing Connection Information ................................................................................ 19 5.1.2. Outbound Connection Type ................................................................................................ 19 5.1.3. Inbound Connection Type................................................................................................... 20

5.2. Connection Configuration............................................................................................................20 5.2.1. Outbound Connection Configuration.................................................................................. 22

5.3. Inbound Configuration.................................................................................................................22 5.4. Metadata Connection ...................................................................................................................22 5.5. Persistence....................................................................................................................................23

5.5.1. Metadata Connection .......................................................................................................... 24 5.5.2. Runtime Connection ........................................................................................................... 25 5.5.3. Persisting Sensitive Properties ............................................................................................ 27

5.6. Tool requirements ........................................................................................................................27 5.7. Discovery service requirements ...................................................................................................28

6. Discovery ......................................................................................................................29 6.1. The MetadataDiscovery Interface ................................................................................................29

6.1.1. ToolContext ........................................................................................................................ 32 6.2. The EIS Metadata Tree ................................................................................................................33

6.2.1. MetadataObjectResponse.................................................................................................... 35 6.2.2. Metadata Object .................................................................................................................. 36 6.2.3. Filtering Properties.............................................................................................................. 38

6.3. Importing Metadata......................................................................................................................38 6.3.1. MetadataImportConfiguration............................................................................................. 38 6.3.2. MetadataSelection............................................................................................................... 39 6.3.3. MetadataObject Selection best practices............................................................................. 40


Page 3 of 114

6.3.4. Tool Code Sample............................................................................................................... 41 6.4. Mutable Metadata Tree (Object Wizard) .....................................................................................43 6.5. Tool requirements ........................................................................................................................47 6.6. Discovery service requirements ...................................................................................................48

7. Importing into a Service .............................................................................................50 7.1. Overview......................................................................................................................................50 7.2. Goals ............................................................................................................................................50 7.3. Architecture..................................................................................................................................51

7.3.1. Service Description ............................................................................................................. 51 7.3.2. Function Description........................................................................................................... 52 7.3.3. Data Description.................................................................................................................. 53 7.3.4. Data Binding Generator ...................................................................................................... 56


8. Property Groups..........................................................................................................59 8.1. Property Descriptors ....................................................................................................................60 8.2. Property Groups ...........................................................................................................................61 8.3. Properties .....................................................................................................................................62

8.3.1. The Property Interface......................................................................................................... 62 8.3.2. The PropertyType Interface ................................................................................................ 63

8.4. Single Typed Properties ...............................................................................................................64 8.4.1. The Single Valued Property Interface................................................................................. 64 8.4.2. The Multi Valued Property Interfaces................................................................................. 66

8.5. Custom Properties ........................................................................................................................66 8.5.1. Tree Properties .................................................................................................................... 67 8.5.2. Table Properties .................................................................................................................. 67

8.6. Property Change Events...............................................................................................................68 8.7. Tool requirements ........................................................................................................................70 8.8. Discovery service requirements ...................................................................................................71

9. Data Handling..............................................................................................................72 9.1. Data programming model ............................................................................................................72 9.2. Data meta-model ..........................................................................................................................72 9.3. Data Bindings...............................................................................................................................72

9.3.1. Data Bindings for Outbound Services ................................................................................ 73 9.3.2. Data Binding for Inbound Services..................................................................................... 74 9.3.3. Generic and Generated DataBindings................................................................................. 75 9.3.4. DataBindingGenerator ........................................................................................................ 76

9.4. Editing support .............................................................................................................................77 9.4.1. ASI Schema......................................................................................................................... 78 9.4.2. EIS Schema ......................................................................................................................... 78 9.4.3. Business Object Schema ..................................................................................................... 79


10. Installing/Bootstrapping/Packaging ..........................................................................81 10.1. Tool requirements ........................................................................................................................82 10.2. Discovery service requirements ...................................................................................................82

11. Runtime ........................................................................................................................83 11.1. Service generation........................................................................................................................83 11.2. Outbound Service.........................................................................................................................83 11.3. Inbound Service ...........................................................................................................................87


Page 4 of 114

11.3.1. Standard Message Listeners................................................................................................ 88 11.3.2. Adapter Specific Message Listener..................................................................................... 92

11.4. Runtime Exceptions .....................................................................................................................93 11.5. Tool requirements ........................................................................................................................94 11.6. Discovery service requirements ...................................................................................................94

12. Edit................................................................................................................................95 12.1. Service description editing...........................................................................................................95

12.1.1. Editing in disconnect mode................................................................................................. 95 12.1.2. Editing in connect mode ..................................................................................................... 98 12.1.3. Type Editing...................................................................................................................... 100

12.2. Administration ...........................................................................................................................101 12.3. Tool requirements ......................................................................................................................101 12.4. Discovery service requirements .................................................................................................101

13. Acknowledgements....................................................................................................102 14. Appendix A: Discovery Service Bootstrap schema................................................103

14.1. discovery-service.xsd.................................................................................................................103 15. Appendix B: Type support .......................................................................................106

15.1. ASI Schema................................................................................................................................106 15.2. Sample EIS Schema ...................................................................................................................108 15.3. Sample Business Object Schema ...............................................................................................110

16. References ..................................................................................................................114


Page 5 of 114

1. Introduction

1.1. Overview SOA is rapidly emerging as the architecture of choice for inter-application communication. Easy interoperability with backend Enterprise Information Systems (EIS) is key to realization of the benefits of SOA. There is a need to be able to rapidly unlock metadata information in EIS systems and quickly develop services that could be used in an enterprise application solution. The term metadata discovery is used to describe this process. A J2EE CA resource adapter is a system-level software driver that is used by a Java application to connect to an EIS. The resource adapter plugs into an application server and provides connectivity between the EIS, the application server, and the enterprise application. The resource adapter serves as a protocol adapter that allows any arbitrary EIS communication protocol to be used for connectivity. It is a natural extension for these resource adapters to provide the capability to browse metadata information of an EIS and assist in building of services. To enable resource adapters to provide this capability there needs to be a standard contract between them and Enterprise Application Integration (EAI) tooling frameworks that use them to generate services. This specification introduces a new metadata discovery and import model for resource adapters and the EAI tooling framework. This model allows resource adapters to easily plug into an integration framework and dramatically improve the usability of adapters within the framework. Using this model, developers are able to gather information about the data and functions of an EIS (using metadata discovery). Having gathered this information, the developer uses the metadata import facilities to define a new custom interface to the required data and functions in the EIS. Any resource adapter that complies with this specification can plug in to any EAI tooling framework that also supports this specification and any EAI tooling framework that supports this specification can use any resource adapter that implements this specification.

1.2. Scope This specification defines a contract between resource adapter providers and the EAI tooling vendors for the following:

• Metadata Discovery

The discovery interface is used to browse the metadata information of an EIS. After discovery, the artifacts that are of interest to the user are imported into a service description. The service description contains all the information required to generate an implementation of the service that can be deployed to an application server. • Mutable Metadata Tree

Apart from discovering the metadata information of the EIS, the discovery service may also choose to support the capability to edit the metadata tree. This is done using the interfaces provided for a mutable metadata tree.

• Connection Persistence This interface allows the user to save and retrieve connections that are used for discovery and runtime. This specification gives the opportunity for the resource adapter to manage its persistence. The tool may also choose to implement its own persistence mechanism.


Page 6 of 114

• Metadata Edit

In some cases a user may want to edit the configuration of the resource adapter or service after it has been created and configured using the discovery and import facility. The Metadata Edit interface provides all the necessary hooks to perform this operation.

• Runtime Support

These interfaces provide additional runtime support for services generated from the discovery process.

1.3. Target audience

The target audience for this specification includes: • Resource adapter providers • Enterprise tool and EAI vendors • Integration framework providers • EIS vendors • Application server vendors and container providers • Enterprise application developers and system integrators

1.4. Organization

This document begins by describing the rationale and goals for creating a standard contract between resource adapter vendors and EAI tool vendors to discover metadata information of an EIS. It then describes the key concepts relevant to the discovery architecture. These sections provide an overall picture of the architecture.

This document then describes typical scenarios for using the discovery architecture. It introduces the various roles and responsibilities involved in the development and deployment of resource adapters and EAI tool that will enable users to browse EIS metadata information and export relevant items into services that can be used by applications. After these descriptive sections, this document focuses on the prescriptive aspects of the discovery architecture

1.5. Document conventions All code fragments and xml fragments are shown in courier font. The document and the API’s define this specification.


Page 7 of 114

2. Overview

2.1. Terms and Definitions This section contains all the terms and definitions that will be used in this document. • EIS Resource

An EIS resource provides EIS-specific functionality to its clients. Examples are: A record or set of records in a database system A business object in an ERP system A transaction program in a transaction processing system

• EIS Metadata This represents all the information that describes an EIS and all the artifacts that are contained within it. A resource adapter may also choose to store metadata information that are not inherently part of the EIS but are related to it. For example, it may store queries that could be made to the EIS. Essentially the resource adapter can augment the EIS metadata information.

• Metadata Discovery This defines the process by which a user may browse the metadata information of an EIS, selecting the artifacts of interest and generating a deployable service.

• EMD (Enterprise Metadata Discovery) This will be the acronym used within this document for Enterprise Metadata Discovery.

• Service Provider This is the term used to refer to a resource adapter that supports the EMD specification.

• Discovery Service Provider This is the term used to refer to a resource adapter that supports the EMD specification and also supports discovery within the EIS for which it is used. Supporting the EMD specification does not necessarily imply that discovery is supported. It could be the case that only editing the resource adapter configuration is supported.

• J2EE CA This term is used to refer to the J2EE Connector Architecture. This term is used to denote both the 1.0 and 1.5 specifications.

• Inbound This term is used for any interaction that occurs from the EIS to an application in an application server.

• Outbound This term is used for any interaction that occurs from the resource adapter to the EIS.

• Tool User This is the term used for a user of an EAI tool for EMD.

• Tooling Framework


Page 8 of 114

The Tooling Framework represents any EAI framework that supports the EMD specification to enable its users to discover metadata using compliant resource adapters. The tooling framework will be referred to as ‘tool’ in the rest of the document.

• Service Interface This term is used to refer to any interface and implementation that is generated by the tool to provide a service. The implementation of the service interface is determined by the tool. This document assumes that the service implementation is generated in Java.

• Service Data Objects (SDO) SDO is a data programming architecture and API for the Java platform that unifies data programming across data source types, provides robust support for common application patterns, and enables applications, tools, and frameworks to more easily query, read, update, and introspect data. See SDO

• Application Specific Information (ASI) This is metadata related to data wire formatting and schema editing that is encapsulated as annotations within a schema describing a request message to an EIS or a response message from an EIS. The EMD XSD provides the appInfo tag for providers to describe application specific information. The discovery service can contribute schema that describes the contents of any annotation appInfo it contributes. Using these schemas, the tool can generically support editing and validation of EIS binding information.

• CCI ( Common Client Interface ) The CCI defines a common client API for accessing EISs. The CCI is targeted towards Enterprise Application Integration (EAI) and enterprise tools vendors.

2.2. Rationale

It is the intention of this specification to augment the J2EE CA specification to allow resource adapters to seamlessly plug into any EAI tooling framework that also supports this specification. The EAI tooling framework can use these resource adapters to discover EIS metadata and create new services or edit existing services which can then be deployed as part of any SOA solution. This specification standardizes the interaction between a resource adapter and any EAI tooling framework that uses resource adapters to discover the metadata of the EIS.

2.3. Goal This specification defines how clients discover and use system capabilities, data structures and communication protocols for an EIS. An explicit goal of this specification is to describe how existing J2EE CA resource adapters may be extended in a straight forward way to provide metadata discovery and import. This can be done with no changes to the adapter’s CCI interface or any of the adapter’s implementation of the system programming interfaces. The changes required are implementation classes for the components of the metadata discovery and import service described later in this specification, and additional packaging information (example, descriptors) needed to register the new implementations. Using adapters that allow for metadata discovery and import, integration developers are able to create and edit services with the following (where the operation style is supported by the underlying adapter)

http://www.jcp.org/en/jsr/detail?id=235


Page 9 of 114

capabilities: • Integration-framework-initiated operations to retrieve data from or do work within the EIS. • EIS-initiated operations, where the request originates within the EIS. This type of operation is used for

retrieving data from, or doing work within, the integration framework.


Page 10 of 114

3. Architecture The following chapter gives an overview of the EMD architecture. The EMD specification defines contracts that extend J2EE CA. The contracts defined in this specification are marked by the bold lines shown in the diagram below. All but one of the interfaces that are defined in this specification are implemented either by the resource adapter provider or a third party discovery service provider and these implementations are packaged along with the resource adapter. Certain classes that facilitate data binding may need to be packaged along with the service interface as the service will need them for data translation. The only interface that is implemented by the tool allows the tool to monitor the activity of the discovery service.

Figure 3.1: The EMD Architecture The four components of the EMD specification are:

Resource Adapter

Application Server

EIS

Application Component

EAI Tooling

EMD

The Tooling generates the

Discovery Metadata

Edit

Runtime

EIS Specific Interface

Container - Component service implementation that Contract can be used by other

applications

Client API

Service Interface

EMD System Contract Tooling


Page 11 of 114

• Runtime These interfaces extend the CCI interfaces defined in J2EE CA to support invocation of services discovered with EMD. These interface implementations are provided by the resource adapter provider or a third party discovery service provider. These are the data binding interfaces that are used to integrate with SDO.

• Discovery

These interfaces constitute the bulk of the contracts defined in this specification. They define the following contracts:

• Discovery These interfaces allow the tool to browse EIS metadata.

• Connections These interfaces allow the tool to discover all the available connections, create connections, edit connections and persist the connections for future use.

• Mutable metadata These interfaces allow the tool to edit the EIS metadata that is being browsed.

• Service Generation These interfaces allow the tool to create or edit service descriptions that define the service a user has selected. These service descriptions are used to generate service implementations that are deployable in application servers and used as part of a SOA. These interfaces also provide support for editing ASI schemas.

These interface implementations are provided by the resource adapter provider or a third party discovery service provider.

• Metadata Edit

This interface allows the EAI tool to edit the configuration of a resource adapter or a service. This interface implementation is provided by the resource adapter provider or a third party discovery service provider.

• Tooling This interface is implemented by the tool and it provides a mechanism for an EMD service provider to perform progress reporting as well as logging and tracing.

3.1. Internationalization

Internationalization is the process of designing software so that it can be adapted (localized) to various languages and regions easily, cost-effectively, and in particular without engineering changes to the software. Localization is performed by simply adding locale-specific components, such as translated text, data describing locale-specific behavior, fonts, and input methods. A lot of the text that is displayed by the tool on its user interface comes from the interfaces that are defined in this specification. It is highly recommended that all these attributes be localized wherever possible. This will make the user experience of the tool more effective. All the attributes that could be used by the tool for display have been explicitly called out in the specification.


Page 12 of 114

3.1.1. Data Transformation Internationalization also applies to data transformations, which includes bi-directional text. A multitude of people use languages that are written in scripts, which are bi-directional. In bi-directional scripts the text is written from right to left while embedded numbers or segments of text in "western" scripts (Latin based ones such as English, French, Cyrillic based, or Greek) are written from left to right. For example consider the following sentence:

I live in MELASUREJ

where the capital letters stand for Hebrew or Arabic characters. “I live in” is written from left to right, while “JERUSALEM” is written from right to left. On different operating systems the bi-directional text is stored differently. The simplest example would be to compare one word having exclusively bi-directional characters: JERUSALEM. On the visual platform (e.g. mainframe) this string is presented in the same order in which it was typed (JERUSALEM). On the logical platform (e.g. Windows) this string is presented in the reversed order as compared to the order in which it was types (MELASUREJ). When exchanging data between platforms having different standards for bi-directional layout it is necessary to transform the data. If the data coming from heterogeneous is not transformed into one common bi-directional format, and this data is used in comparison operations as part of business process logic, it will cause the business process to fail. Data transformation is performed by the DataBinding or CCI Record, as described in section 9.3 . The recommended common bi-directional format is described below. The base concepts of bi-directional attributes described by OMG, Open Group, Unicode or Windows are consistent. These attributes are shown below along with possible values. OMG Common Application Meta Model

Open Group Unicode Windows Valid values

Text Type Text Type Memory representation and display ordering

Logical and visual • Implicit or logical

• Visual Orientation Global orientation Base direction or

paragraph direction

Reading order • LTR • RTL • Contextual

LTR • Contextual

RTL Symmetric Symmetrical

swapping Mirroring Swapping of

symmetric pairs • True • False

Numeral shape National numbers Decimal forms National and nominal digits

• Nominal • National • Contextual


Page 13 of 114

Text shape Shaping Shaping Arabic form shaping

• Nominal • Shaped • Initial • Middle • Final

For Windows:

• The default text type value is logical (implicit). Visual is only available for presentation devices. • The default orientation is LTR. • Symmetric is always true. • Only nominal code points for numerals are fully supported (including generation from the

keyboard). • Only base code points for Arabic letters are fully supported (including generation from the

keyboard). Windows Arabic code page (1256) only has code points for western digits and base letter forms, so it only supports encoding of nominal shapes of digits and Arabic letters. It is recommended that any bi-directional transformations occur here to a canonical form. The recommended canonical form is:

• Text type: implicit • Orientation: LTR • Symmetric: swapped • Numeral shape: nominal • Text shape: nominal


Page 14 of 114

4. Roles/Scenarios

4.1. Roles The following are the different roles and responsibilities that are involved in the scenarios described in this section.

4.1.1. Business Analyst A business analyst understands enterprise information systems and the overall business processes in the enterprise. They are well versed in the client tools of the major enterprise systems being used within a company. Generally, they deal directly with the EIS client tools, but on occasion use the client tools for an integration environment or application server that links those enterprise systems together. The latter point underscores the fact that the domain expert often does not communicate their domain expertise directly into the client tools for the integration environment. Rather, they communicate their expertise through a third party that is focused on working with the tools provided by the integration environment. They are experts in enterprise systems such as enterprise resource planning (ERP) and customer relationship management (CRM), and know which business objects offered by those systems are appropriate for use in business processes hosted in the integration environment or application server. They can look at the data definitions for a business object or function and understand the elements contained in them. They are also responsible for describing to developers the usage of business objects in the enterprise system. The most important characteristic of an integration tool environment to a business analyst is that it makes it easy for them to communicate information about business objects and functions to developers. The developers can then take responsibility for implementing new interfaces to the enterprise systems. This leaves business analysts free to concentrate on the overall use of enterprise data and not the particulars of the interfaces to the enterprise systems that host it. Closest J2EE Role: The role of a business analyst does not map to a J2EE role.

4.1.2. Developer A Developer is a tool user. They are proficient at using the tool environment to create service-based solutions. They have a good understanding of how the tool environment allows them to make outbound calls to an EIS and receive inbound notifications and calls from the EIS. However, a developer looks to a business analyst to provide connection details for each EIS involved in a business process and the specific functionality or business objects to use within the process. A developer also looks to a business analyst to guide them on the interpretation of business objects, data types, and so on. The most important characteristics of an integration tool environment to a developer are: • Make it easy to communicate with the business analyst about business objects and their use • Make it easy to define new services backed by enterprise systems. Closest J2EE Role: A developer would be considered to be an application component provider and application assembler.

4.1.3. Administrator An administrator manages day-to-day administration of applications. They generally take over an application after a developer has finished developing and testing it. An administrator uses the application


Page 15 of 114

server’s management console to stop and restart applications, handle outage from an EIS going down, change an existing application to point to a different instance of an EIS, set user roles and permissions, and provide status and statistics on the general health of the system. An administrator may also be involved with installing and configuring resource adapters within a tool environment. Closest J2EE Role: An administrator would be considered to be a deployer and system administrator.

4.2. Creating a Service This scenario describes how a business requirement is transformed into a service implementation using EMD. 1. A business analyst defines the business requirement and communicates it to a developer. 2. The developer takes these business requirements and performs the following steps to create the service implementation. The figure below shows the process that she will follow to achieve this.

Figure 4.1: Creating a service

a. Browse Metadata information Using the EAI tool, the developer connects to an EIS system and browses the metadata. While browsing the metadata, the user then locates and selects the artifact of interest. It might be the case that the user is interested in more than one artifact and selects all of them. b. Define service description The developer aggregates EIS metadata into a service description. The service description cannot be directly invoked from Java code, but instead contains all the information needed to generate a service interface. The developer defines the service description by picking artifacts, the style of the interaction


Page 16 of 114

(event from EIS, request to EIS and so on) and configuration information that controls the interaction with the EIS. c. Build service interface and implementation The developer directs the tool to generate a service interface and implementation for the service description. The tool generates a service interface for the service and any classes or J2EE modules that are needed to implement the service. The exact form of the service interface and the generated service implementation are tool-specific. One tool may choose to generate the service interface and implementation as a simple Java interface and class, respectively. Another tool may choose to generate the service interface and implementation as an Enterprise JavaBeans (EJB) remote interface and bean implementation, respectively. Put simply, each tool would generate a service interface and implementation that corresponds to the programming model it supports.

3. After the service interface is built and implemented. The developer directs the tool to package and deploy the application. This may be done in a managed environment, or if the service is outbound it can also be done in a non-managed environment. Testing the assembled application as a whole would be a step to delivering the finished application to the administrator for down-stream environments such as acceptance testing and production. Tool vendors are free to choose whether to provide integrated packaging and deployment support from within the same tool used to develop the service. The application archive would contain the generated service interface and implementation and any other classes such as user-written business processes, web services and so on. The resource adapter archive modules needed to support inbound or outbound communication may be contained in the application archive or deployed separately. Note that the tool can package the final application archive so it can run on a standard J2EE, Version 1.4 server.

4.3. Editing connection information This scenario describes the case where a new EIS instance has been installed and all services must be re-configured to point to this new EIS instance. This may be the case when a service is being moved from the test environment to the production environment.

1. The business analyst informs the administrator that there is now a new EIS system that all services must now use.

2. The administrator uses the EMD tool, which in turn uses the Metadata Edit interface defined by this specification. Using the tool the administrator is able to view the current configuration of the service and update all the relevant connection information such as URL, password etc. to point to the new EIS.


Page 17 of 114

4.4. Sample Enterprise Application

ERP System Implementation

Customer Sink ERP

Resource Adapter

Process Implementation by Developer Customer Source MDB

CRM System

Implementation

Customer Source

Implementation

CRM Listener

CRM Resource Adapter

Provided by the Developer

Provided by the Resource Adapter

Generated by the tool

Figure 4.2: Sample enterprise application The diagram above shows a sample enterprise application constructed by a developer who has used EMD. It shows an enterprise implementation that depends upon inbound messages from a CRM system and outbound communication to an ERP system. The CRM system holds all the customer information and ERP system holds all the orders placed by the customer. The resource adapter and the listener interface are provided by the Resource Adapter vendor. Using the tool the developer generates the implementation for the Message Driven Bean and the service interfaces. After the service interfaces are generated, the enterprise process implementation that uses the generated service implementations is provided by the developer.


Page 18 of 114

5. Connections The adapter establishes a connection to the EIS system and exchanges data using this connection. This section describes how the connection information is specified, how connections are configured and how can they be persisted. The connection interfaces are defined in the commonj.connector.metadata.discovery.connection package. The AdapterType, an object representing the metadata about an adapter specifies the set of connections it supports. The array of Connection Types provided by an adapter type characterizes its connections, specifying inbound and outbound connection types as well as other information about connections such as whether these connections can be used for metadata discovery.

5.1. Connection Type A ConnectionType represents a connection supported by an adapter type. It is a factory for ConnectionConfiguration instances. It creates instances that can be configured, used by the tool to create actual connections, and then persisted for later use. The connection can be inbound or outbound and is unique within the AdapterType. A specific type of the adapter can have multiple types of connection for inbound as well as outbound communication. For example it can define different connection types that represent different types of access protocols to the EIS system. The following figure presents the ConnectionType interfaces:

Figure 5.1: Connection interfaces


Page 19 of 114

All connections within AdapterType are represented by a unique ID used to identify the type of connection. Because of such scope, each connection type keeps reference to its adapter type. The connection type also provides display name and description that helps the tool user to determine which connection is appropriate for a specific task. Both display name and description are locale sensitive. A ConnectionType can optionally provide an instance of ConnectionPersistence. If persistence is not supported, the connection indicates this by returning null from the getter method. Connection persistence is described in detail in section 5.4 of this document. The connection type represents information that characterizes a particular type of connection. These properties are embedded in a ConnectionConfiguration object created by the ConnectionType and described in the next section. The ConnectionType also provides a method that allows a tool to determine whether the ConnectionConfiguration is complete, that is whether it can be reasonably assumed to contain enough information to establish a physical connection to the EIS. The intention of this method is to allow tools to determine whether the returned ServiceDescription (see section 7.3.1) contains sufficient connection information or whether more information should be obtained from the user. It is not possible to verify correctness of the information, only its presence. An example would be a host name of the system running the EIS, without this information, the service cannot be executed, with it, the adapter can make a reasonable assumption that it can. Of course if the host name is incorrect, an attempt to establish a connection will fail.

5.1.1. Representing Connection Information The properties of the connections can be viewed in two different representations depending on the use, the tool time and the runtime. The ConnectionConfiguration is a tool representation of the connection properties based on the PropertyGroup (see section 8), the runtime configuration is represented by the Connector Architecture specification interfaces, resource adapter JavaBeans: ResourceAdapter, ActivationSpec and ManagedConnectionFactory. There is a need for synchronization between these two representations and the ConnectionType provides methods to perform such synchronization. Furthermore, the tool time representation of the connection information, ConnectionConfiguration is presented in two views, the unified view and per bean view, as discussed in the Connection Configuration section.

5.1.2. Outbound Connection Type The OutboundConnectionType is a specialization of the ConnectionType for outbound connections; connections from the application server to the EIS system. It augments the base interface with the outbound specific information and methods. It allows for creation of the OutboundConnectionConfiguration that contains all the properties for configuring the outbound connections. Since the outbound connections can be used at runtime as well as for the metadata discovery, the outbound type provides methods that allow the caller to ascertain whether a given connection type is suitable for runtime or metadata discovery or both. This can help the tool to present to the user with a set of connections suitable for their intended use. The OutboundConnectionType provides methods to create both representations of the outbound connection, the tool time OutboundConnectionConfiguration as well as OutboundConnectionBeans, a


Page 20 of 114

runtime representation of the connection containing instances of the ResourceAdapter and the ManagedConnectionFactory Java beans. In addition, it provides set of methods to synchronize between these representations specific to the outbound connections, that is to map or transfer properties from one representation to existing instance of the other representation. It allows synchronizing between ManagedConnectionFactory Java bean and configuration property group as well as mapping between unified connection properties and the outbound connection beans. The unified set of properties contains all the properties necessary for outbound communication using a given connection type. It presents to the user a uniform view of all information that needs to be supplied to achieve outbound connectivity. This allows the user to configure connections without knowledge about the internals of the adapter. The unified properties hide from the user the fact that properties are configured on two separate runtime Java beans. Metadata discovery involves the tool making requests of the EIS (through the discovery service) and thus the connection used by metadata discovery is an outbound connection. Because of this, the OutboundConnectionType also provides a method to establish a discovery connection, a MetadataConnection given an outbound connection configuration. The method should open the connection with the EIS system so that the returned connection can be used directly for metadata discovery. The returned connection will only be used for discovery and the caller cannot make any assumptions about its suitability for runtime use. The OutboundConnectionType properties that characterize the outbound connection could include properties such as the name of the RDBMS host, the port number and the password to access the specific set of database tables, the set of properties matching the properties of the ManagedConnectionFactory JavaBean of the Resource Adapter.

5.1.3. Inbound Connection Type The InboundConnectionType is a specialization of the ConnectionType for inbound connections from the EIS to the application server. It allows for creation of InboundConnectionConfiguration instances with all the properties for configuring inbound connections. The InboundConnectionType defines the InboundConnectionBeans interface containing ResourceAdapter and ActivationSpec JavaBeans that represent runtime inbound connection information. Similar to outbound, the inbound connection type provides methods to create both tool and runtime representations of the configuration and to synchronize between these representations. The InboundConnectionType properties that characterize inbound connection and can include, for example, the polling frequency, an interval at which a database tables are checked for the changes. The changes, once detected would then be propagated as the inbound service by invoking method on the adapter message listener interface.

5.2. Connection Configuration A ConnectionConfiguration represents a complete set of properties to configure or create a connection of the specific ConnectionType. The configuration is used for all exchange of connection information; it is passed in the tooling environment, persisted to permanent storage and synchronized with the runtime


Page 21 of 114

representation Java beans. The ConnectionConfiguration interfaces are presented in the following figure.

Figure 5.2: The connection configuration interfaces

Since the configuration can be persisted and exchanged, EMD allows for a configuration’s name and description to be customized by the tool user. This allows for user defined name and description modifications to be contained without the need for any additional wrapping by tools. The tool must allow for setting of the name and description. The configuration is created by the connection type. The configuration is defined using properties defined by the connection type. A configuration must keep a reference to the ConnectionType that created it. The ConnectionConfiguration provides two views of its properties, the unified view suitable for majority of user and per bean view that can be used in some circumstances by advanced users. The unified properties view presents all the properties necessary to configure the inbound or outbound connection together, irrespectively of to which runtime Java bean they belong to. In most cases it is sufficient, a set of properties needs to be set to configure connection and specific bean they map to is not relevant to the user. For the rare cases when the specialized knowledge is necessary, the ConnectionConfiguration provides per bean view of its properties, a view showing properties corresponding to the specific Java bean of the adapter. The tool can choose, based on the use preference, either of the two views of the ConnectionConfiguration, the unified editing of the connection or the per bean configuration editing with the separate properties for the ResourceAdapter Java bean and ActivationSpec or ManagedConnectionFactory.


Page 22 of 114

The configuration interface provides methods to create either view properties, represented by the PropertyGroup. When one of the create methods is invoked for the first time, the returned PropertyGroup will contain the default values of the properties (unified or per bean). The group can then be used by the tooling environment to display properties to the user, query user for their values, persist them and so forth. The ConnectionConfiguration does not keep the association with the property group or groups it created and does not need to update its contents as the property group is modified. This allows tool environment for the most efficient, disconnected operations on the properties. The update of the ConnectionConfiguration with the values of the properties is an explicit step, the invocation of the appropriate apply method.

5.2.1. Outbound Connection Configuration The OutboundConnectionConfiguration extends the ConnectionConfiguration for the configuration of outbound connections. It adds, to the base interface, methods to create and apply per bean configuration specific for outbound connections; that is configuration of the ManagedConnectionFactory. It also provides the typed getter method to retrieve the OutboundConnectionType that created this configuration.

5.3. Inbound Configuration The InboundConnectionConfiguration extends the ConnectionConfiguration for the configuration of inbound connections. It adds the methods to create and apply ActivationSpec properties and to retrieve the InboundConnectionType that created this configuration.

5.4. Metadata Connection The MetadataConnection is a connection used during service discovery to browse and import EIS metadata. It is specified by the set of properties contained in an OutboundConnectionConfiguration. Its corresponding ConnectionType is defined to return true from its isSupportedInMetadataService method. The interface is shown in the following figure.

Figure 5.3: The MetadataConnection interface

The MetadataConnection is created by the OutboundConnectionType. The user selects an AdapterType, and then the connection type to be used for metadata discovery from the list of suitable connection types presented by the tool. This list is generated from the list of connection types for the selected adapter type that indicate they are supported for use in the metadata service; that is they return true from the isSupportedInMetadataService method. The selected ConnectionType is used to create the OutboundConnectionConfiguration. The user is asked to populate configuration properties and once


Page 23 of 114

the properties are applied, the configuration is passed to the connection type method openMetadataConnection to establish the connection for metadata discovery. The metadata connection configuration is used only for metadata discovery and does not need to be a valid runtime connection. The user can make no assumption about its suitability for the use at runtime. The implementation of the MetadataConnection is adapter specific. It must be usable for discovery but does not necessarily require network connectivity of any kind. An example of such a connection would be one that connects to a local metadata file. The MetadataConnection provides accessors to its ConnectionType and ConnectionConfiguration.

After the tool finishes using a metadata connection, it must invoke its close method. This gives the discovery service a chance to perform necessary cleanup, like closing files or sockets, before discarding the connection. Any use of the metadata connection after its close method has been invoked is an error and must result in an exception.

5.5. Persistence The ConnectionPersistence mechanism allows the discovery service and the tool to persist the ConnectionConfiguration for a connection. It helps to avoid repetitive entry of the configuration information and allows for a separation between configuration and the use of connections. This improves usability by allowing reuse of stored configurations. The ConnectionPersistence is presented in the following figure:

Figure 5.4: The connection persistence interfaces.

The persistence may be implemented by the discovery service and by the tool. While its support is optional for both, it is recommended that the tool support it for a consistent and robust user experience.


Page 24 of 114

If the discovery service supports persistence, the tool must use it to store and retrieve connection configuration. If the tool provides its own persistence, it may use this persistence implementation in addition to any implementation provided by the discovery service. If the discovery service does not support persistence, any persistence support comes exclusively from the tool. When persistence is supported by the discovery service, it is accessed via an instance of ConnectionPersistence created using ConnectionType. This does not limit the persistence scope to just the ConnectionType used to create it. Any given ConnectionPersistence instance could be applied to multiple connection types or even multiple adapter types but it must be able to store the ConnectionType that created it. Since the ConnectionPersistence instance can be shared even between adapter types, the key that uniquely defines the connection configuration must include AdapterType ID, connection type ID and the connection configuration name. This imposes the uniqueness requirements on the discovery implementation. For example the ConnectionType ID must be unique within the adapter type. In addition, the persistence implementation must enforce requirements of the uniqueness of the configuration name. The persistence provides methods to add remove and verify the existence of the persisted ConnectionConfiguration. When the configuration is added to the persistence, the caller can specify whether the configuration should be overwritten, if it already exists. ConnectionConfiguration contains an arbitrary number of properties and could potentially be a large object that could not be manipulated easily. For that reason, the persistence introduces ConnectionSummary interface that contains the basic connection information such as name, description, connection type and whether the connection is inbound or outbound. The array of connection summaries is returned when the persistence is queried for the persisted connection configurations. The summary is used as the key to retrieve or remove connection configuration. All types of connection configurations can be persisted including a metadata and runtime connections. The samples below present the execution flow, without user interface, of how both of these connection types can be persisted.

5.5.1. Metadata Connection The scenario of persisting and reusing metadata connection can be as follows:

• The user selects OutboundConnectionType from the list presented by tools. It is based on the array of ConnectionTypes from the AdapterType and includes connections supporting discovery.

• The ConnectionPersistence instance is retrieved from the selected ConnectionType • If the retrieved ConnectionPersistence instance is null, the discovery service does not support

persistence. The tool may use its implementation if it is supported. • Given the persistence, the tool retrieves an array of connection summaries, for the given

connection type and presents it to the user • When the summary is chosen, the tool retrieves matching outbound connection configuration

AdapterType adapterType = … // Created by the tool environment OutboundConnectionType[] outboundCTArray = adapterType.getOutboundConnectionTypes();


Page 25 of 114

// Simulate the user picking a ConnectionType from the list OutboundConnectionType connectionType = outboundCTArray[0]; ConnectionPersistence persistence = connectionType.getConnectionPersistence(); if (persistence == null){ // get persistence from tooling, if it is available } ConnectionPersistence.ConnectionSummary[] connSummaries = persistence.getConnectionSummaries(connectionType.getID()); // Simulate the user picking a configuration, by summary, from the list OutboundConnectionConfiguration metadataConfiguration = persistence.getOutboundConnectionConfiguration(connSummaries[0]); // … // if (metadataConfiguration == null){ metadataConfiguration = ct.createOutboundConnectionConfiguration();

// Set configuration properties (We just hard-code them here) … metadataConfiguration.setName(“Name”); metadataConfiguration.setDescription(“Description”); // Persist the metadata connection if(!persistence.exists(metadataConfiguration)) persistence.addConnectionCofiguration(metadataConfiguration, false); } // Open connection for discovery MetadataConnection metadataConnection = connectionType.openMetadataConnection(metadataConfiguration); // use the metadata connection

If there is no persisted connection, the new configuration is created, and then persisted if possible.

5.5.2. Runtime Connection The ConnectionConfiguration may require additional configuration information to be usable at runtime. The isConnectionConfigurationComplete method on the ConnectionType indicates whether connection information is complete.

The information can be incomplete for any number of adapter specific reasons. However, one common scenario of incomplete connection information is when the service requires a different type of connection at runtime than was used during discovery. For example, if discovery was performed against a local metadata file, but at runtime a live EIS instance is required, it is likely that the user will need to provide extra information to allow for a valid runtime connection to be established. Also, inbound services require an InboundConnectionConfiguration, and often this type of configuration cannot be fully specified using information from the metadata (outbound) connection configuration.


Page 26 of 114

The sequence of replacing the connection configuration, instead of augmenting it in place, returned as part of the service description is as follows.

• The ConnectionConfiguration is retrieved from the ServiceDescription. • The configuration is verified for completeness. • If it is not complete, the ConnectionType is retrieved from the configuration. • The ConnectionType is used to retrieve ConnectionPersistence. If the persistence is not

supported by the discovery service, the tool persistence, if available, is used. • The array of stored connection summaries is retrieved from the persistence using the

ConnectionType. • The user selects the ConnectionConfiguration based on the returned summaries; the

configuration is then applied to the ServiceDescription to be used by tools to serialize the service.


Page 27 of 114

InboundServiceDescription serviceDescription = … InboundConnectionConfiguration inboundConfiguration = serviceDescription.getInboundConnectionAdvancedConfiguration(); boolean complete = connType.isConnectionConfigurationComplete(inboundConfiguration); if (!complete) { InboundConnectionType inboundType = inboundConfiguration.getInboundConnectionType(); ConnectionPersistence connectionPersistence = inboundType.getConnectionPersistence(); if (connectionPersistence == null) { // Use persistence provided by tooling } ConnectionPersistence.ConnectionSummary[] storedConns = connectionPersistence.getConnectionSummaries(inboundType); InboundConnectionConfiguration savedInboundConfiguration = connectionPersistence.getInboundConnectionConfiguration(storedConns[0]); serviceDescription.setInboundConnectionAdvancedConfiguration( savedInboundConfiguration); }

5.5.3. Persisting Sensitive Properties The ConnectionConfiguration being persisted may contain sensitive properties such as passwords or encryption keys. Values of such properties must never be persisted without taking appropriate security measures such as providing a warning message that the sensitive property will be saved in clear text or encrypting the property.

5.6. Tool requirements Tool vendor must

• Present to the user localized version of the ConnectionType display name and description. • Warn the tool user if the ConnectionConfiguration is not complete before serializing service

description. • Use the Resource Adapter Persistence if provided by the adapter. • Invoke close method on the MetadataConnection after finishing using the connection.

Tool vendor should

• Provide an implementation of ConnectionPersistence. • Allow user to specify the name of the connection to be persisted. • Take appropriate action when persisting sensitive properties, such as encryption or warning the

user that sensitive properties may be stored in open text.


Page 28 of 114

5.7. Discovery service requirements Resource Adapter must

• Identify each adapter type by the unique ID. • Identify each connection type by ID unique within adapter type. • In the ConnectionType, maintain reference to the AdapterType. • In the ConnectionConfiguration, maintain reference to ConnectionType. • Provide ConnectionConfiguration containing properties corresponding to properties found on

the Resource Adapter runtime beans and populate it with the default values. • Provide two views, unified and per bean of the configuration properties. • Return null from ConnectionType.getConnectionPersistence() if it does not support

ConnectionPersistence. • Identify and indicate through appropriate API, the completeness of the connection configuration.

The Resource Adapter must return false if any of the mandatory properties of the configuration has not been set.

• Provide MetadataConnection if the adapter supports service discovery. • Take appropriate action when persisting sensitive properties, such as encryption or warning the

user that sensitive properties may be stored in open text.


Page 29 of 114

6. Discovery A key component of functionality, provided by this specification, is the ability to discover EIS metadata. This metadata is used to generate a service interface that can be used by a client to interact with the capabilities of the EIS. The interfaces contained within the commonj.connector.metadata.discovery package define the necessary interactions in order to browse, and discover, the metadata within a given EIS. Discovery service providers must supply implementations for all the interfaces defined in this package. Tools must interact with these implementations, in order to drive the discovery on behalf of a given user. The general flow of EIS discovery is shown in the figure below:

1. Get Metadata

2. Use connection to create Metadata Tree

3. Use Metadata Tree to query EIS and get a filtered tree representation of its metadata.

6. Configure selected nodes.

5. Select metadata nodes for import.

4. Navigate the tree, expanding various metadata nodes.

7. Configure entire selection.

8. Import selection into a service description.

Figure 6.1: General Flow of EIS Metadata discovery The following sections discuss this flow in further detail, and outline the interfaces that provide the functionality in each of the steps.

6.1. The MetadataDiscovery Interface Any interaction between a tool and an EIS must originate with an implementation of the MetadataDiscovery interface.


Page 30 of 114

Figure 6.2: The MetadataDiscovery Interface A service provider must provide one, and only one, implementation of the MetadataDiscovery interface. This implementation is registered within the tool as part of the bootstrapping process described in section 10. In order for the tooling to be able to instantiate an instance of the MetadataDiscovery, the implementation must support a default no-argument constructor. The tool uses the MetadataDiscovery implementation as its handle to the capabilities of the service provider. The MetadataDiscovery instance exposes the available set of AdapterTypes supported by the discovery service. The AdapterType interface provides the tool with a handle to the various inbound and outbound connection types supported by the discovery service. The AdapterType only returns those connection types it supports, and NULL otherwise. For example, an adapter that supports only J2EE CA version 1.0 would return NULL from getInboundConnectionTypes(), since inbound communication is not supported.

Figure 6.3: The AdapterType Interface

One of the first things a tool needs to know from a service provider is the set of AdapterTypes it supports. This is achieved by getting the set of AdapterTypeSummary objects, for all the AdapterTypes supported by the provider, by calling the getAdapterTypeSummaries() method on the MetadataDiscovery Implementation. An AdapterTypeSummary provides a summary description of a given AdapterType. This description includes:

• The locale sensitive display name for the AdapterType. • A locale sensitive description for the AdapterType. • The vendor name and version of the AdapterType. • A unique string identifier to use as a key to locate the corresponding AdapterType. • A Boolean flag [hasMetadataConnectionTypes()] that indicates whether the associated

AdapterType supports ConnectionTypes that can be used for discovery. The tool must present the set of available AdapterTypeSummary objects to the user. The user would be expected to select a particular AdapterTypeSummary to interact with. If the user wishes to perform metadata discovery, then the selected AdapterTypeSummary must be one that supports ConnectionTypes that can be used for discovery. The tool may wish, in this case, to limit the user’s selection to only those AdapterTypeSummary objects which return true from hasMetadataConnectionTypes().


Figure 6.4: The AdapterTypeSummary Interface

Having selected an AdapterTypeSummary the tool must then obtain its associated AdapterType. This is done by retrieving the String identifier of the AdapterType, by calling getId() on the selected AdapterTypeSummary. Using this identifier the tool obtains the actual AdapterType via a call to getAdapterType(String id) on the MetadataDiscovery implementation. Once the tool obtains the AdapterType it can access its available ConnectionTypes. For metadata discovery, the tool can create a MetadataConnection from an OutboundConnectionType that supports discovery. Refer to section 5.3 for details on creating a MetadataConnection. Once a MetadataConnection is obtained it can be used to begin browsing the available EIS metadata. This is done by acquiring a MetadataTree instance from the MetadataDiscovery implementation, using the MetadataConnection as the creation parameter (the getMetadataTree method on the MetadataDiscovery interface). It is important to note that the lookup for an AdapterType is split into a two step process as a performance optimization. It is expected that the implementation of an AdapterType would be a heavy weight object due to the ConnectionType information it holds (which may require it to hold physical connections to an EIS system). If this is the case, it would be sub-optimal to require the tool to retrieve the complete set of heavy weight AdapterTypes only to select one to interact with. Hence the AdapterTypeSummary is used to provide a lightweight view of the set of available AdapterTypes. However, if a particular adapter’s implementation does not require the AdapterType to be a heavy weight object then it can easily implement the AdapterTypeSummary and AdapterType as the same class.

The sequence diagram below illustrates how a tool can obtain an AdapterType from an EMD provider:

Page 31 of 114


Page 32 of 114

Figure 6.5: Obtaining an AdapterType

6.1.1. ToolContext When performing metadata discovery, the operations involved could potentially take longer than a couple of seconds to complete. For example, retrieving EIS metadata objects over a MetadataConnection. In order to make the tools user friendly, there must be some feedback mechanism to the tool user that updates on the progress of operations. Furthermore, in the case of discovery failure, the user should have some meaningful error log and trace output to examine. The EMD specification defines a commonj.connector.tool.ToolContext interface to handle progress monitoring, and logging and tracing. The implementation of this interface must be provided by tools. The ToolContext is passed, by the tool, to the discovery service provider. The service provider is responsible for updating its operation progress, as well as logging and tracing, using the provided ToolContext. Since discovery can only occur with a live MetadataConnection, the ToolContext is set on the MetadataConnection. A ToolContext is also set on the MetadataDiscovery implementation, however this context must only be used to report progress and log any activity that occurs in the process of creating a MetadataConnection.

Figure 6.6: The ToolContext interface

The ToolContext provides a standard java.util.logging.Logger, as well as a progress monitoring interface. The logger provided by the tool is only guaranteed to handle standard java.util.logging.LogRecord records. Discovery service providers must use all the facilities of the progress monitoring interface to communicate operation progress with the tool. This includes updating progress using the setNote and setProgress methods, as well as responding to requests from the tool to cancel any ongoing operation via the isCanceled method.


Page 33 of 114

Discovery service providers should provide logging and tracing output using the Logger from the ToolContext. At a minimum, severe errors should be logged. It is recommended that service providers also support finer levels of logging and tracing as a problem determination mechanism for tool users.

6.2. The EIS Metadata Tree The metadata from EIS systems come in various formats; however these heterogeneous forms can always be modeled in a logical tree representation. Each node in the tree corresponds to an underlying metadata object residing on the EIS. Not all metadata objects can be imported. For example some objects may simply be containers used to group together a set of importable metadata. In such cases the container itself may, or may not, be importable as well. In the EMD specification, this tree representation is provided via an implementation of the MetadataTree interface. The tool obtains an instance of the MetadataTree from the MetadataDiscovery implementation, using a previously created MetadataConnection. The MetadataTree provides the root handle for the tool to browse all the available EIS metadata, as nodes in a canonical tree representation. The nodes correspond to MetadataObject instances which represent the actual EIS metadata being discovered. Section 6.2.2 describes the MetadataObject in detail. The MetadataTree interface provides the following functionality:

• A handle to the MetadataConnection used to create it [getMetadataConnection()]. • A hint to the tool UI on the selection style supported by the canonical tree. The supported styles

are SINGLE_SELECT and MULTI_SELECT. The supported selection style is retrieved from the getSelectionStyle() method. If the returned style is SINGLE_SELECT then the tooling UI can assume that only a single node in the tree can be selected for import at any given time. If the returned style is MULTI_SELECT then it is assumed that multiple nodes can be selected for import simultaneously. It is important to note that it is not the duty of the tool to enforce this selection. Instead the selection behavior is implemented, and enforced, by the underlying MetadataSelection. See section 6.3.2 for further details on the MetadataSelection.

• A factory method [createMetadataSelection()] to create a MetadataSelection implementation to be used by the tool to select metadata for import. See section 6.3.2 for further details on the MetadataSelection.

• A factory method [createFilterProperties()] to create a PropertyGroup that specifies the query filtering parameters available on the metadata tree. Section 6.2.3 describes filtering properties in detail. See section 8 for further details on the PropertyGroup interface.

• A method to perform an initial query on the metadata tree [listMetadataObjects()].A MetadataObjectResponse object, with the query result set, is returned from this method. See section 6.2.1 for further details on the MetadataObjectResponse.

• A retrieval method [getMetadataObject()] that can retrieve a particular MetadataObject from the MetadataTree using its location identifier.


Page 34 of 114

Figure 6.7: The MetadataTree interface

When performing metadata discovery, the typical sequence of activity for the tool involves the following:

1. Obtaining a MetadataTree instance using a MetadataConnection. 2. Determining the selection style of the MetadataTree so that the tool can prepare the appropriate

UI rendering. 3. Retrieve the available query filter parameters available on the MetadataTree as a

PropertyGroup. Render the PropertyGroup to the user and allow for the setting of filter values. 4. Perform a query on the MetadataTree using the configured filter parameters. 5. Display the results of the query, which are returned in a MetadataObjectResponse instance.

The sequence diagram below illustrates the typical query of the MetadataTree:

Figure 6.8: Querying a MetadataTree


Page 35 of 114

6.2.1. MetadataObjectResponse When queries are performed on the MetadataTree, the result set that is returned must be presented to the user. This is to allow the user to select MetadataObjects to import, or to allow for further navigation of the MetadataTree. In order to properly present the result set, a MetadataObjectResponse object is used. The MetadataObjectResponse interface provides the following functionality:

• A handle to any locale sensitive messages [getMessage()] that may have been associated with the result set. Some examples of such messages include:

o an error message when the result set is empty due to invalid configuration of the filter parameters, and

o a warning message that the result set returned is very large and that the user may wish to scope the search further using the filter parameters.

• An iterator for the tool to use to cycle through the children MetadataObjects returned in the result set. The iterator is an instance of the MetadataObjectIterator interface. This interface extends the base java.util.Iterator with convenience methods to retrieve the next MetadataObject and to retrieve the total size of the result set.

Figure 6.9: The MetadataObjectResponse and MetadataObjectIterator interfaces.

The use of an iterator is beneficial for both the discovery service provider and the tool. For the discovery service provider, it allows for the lazy fetching of MetadataObjects from the EIS system. Instead of pre-fetching the entire set of MetadataObjects, the provider can only pre-fetch a few and incrementally fetch more as the nextMetadataObject() method is called and the pre-fetch cache is depleted. For the tool, it allows for the optimal retrieval of MetadataObjects. For example, if a particular tool is only able to display 20 MetadataObjects at any given time, due to UI layout constraints, it would be sub-optimal to have it retrieve the entire result set only to show the first 20. By using an iterator, the tool is able to only retrieve the set of MetadataObjects it needs at any given time. The sequence diagram below illustrates the use of the MetadataObjectResponse by a tool:


Page 36 of 114

Figure 6.10: Using the MetadataObjectResponse and MetadataObjectIterator interfaces

6.2.2. Metadata Object The MetadataTree, MetadataObjectResponse, and MetadataObjectIterator interfaces only provide the mechanisms needed to navigate through the EIS metadata. It is the MetadataObject interface that actually represents the metadata content itself. Each MetadataObject instance has a direct mapping to an EIS metadata artifact. The nature of this mapping is outside the scope of this specification and it is up to the domain of the discovery service provider to determine the appropriate mapping required.


Page 37 of 114

Figure 6.11: The MetadataObject interface

The MetadataObject provides the following functionality:

• A locale sensitive display name and description to be used by the tool to display the object. • A string identifier for the object’s location within the MetadataTree. This is the location that

must be used whenever a call to MetadataTree.getMetadataObject() is called. This identifier is provided by the discovery service implementation and it must be unique and persistent. In other words, the discovery service must support using the same identifier at a later point in time to retrieve the identical MetadataObject

• A string identifier for the parent MetadataObject, if a parent exists. This identifier must be identical to the identifier returned from the parent MetadataObject.

• A flag indicating the type of the MetadataObject. The type is represented by a MetadataObjectType instance. The type serves only as a hint to the tool as to the nature of the MetadataObject. This hint may be used by tools to apply special rendering logic when displaying the MetadataObject. For example, MetadataObjects that are identified with a MetadataObjectType.FOLDER may be rendered with a different icon that resembles a folder.

• A handle to the children MetadataObjects [getChildren()]. The handle returned is an instance of MetadataObjectResponse in order to make use of the performance and usability features offered by this interface. The getChildren()accepts a PropertyGroup as an optional parameter. This PropertyGroup represents any filtering parameters that are to be applied when obtaining the children MetadataObjects. This facility can be used by tool users to further limit the result set as they navigate through the MetadataObjects that comprise the MetadataTree. The convenience method [hasChildren()] should be used by tools before making a call to getChildren() since it allows the tooling to determine upfront if the MetadataObject has any children or not.

• A factory method [createFilteringProperties()] to obtain the PropertyGroup that can be used to filter the children MetadataObjects. If filtering is not supported then NULL is returned from this factory method. Tools can retrieve the active filtering parameters that have been used to obtain the children MetadataObjects via the getAppliedFilter() method.

• Optional read only properties that provide additional descriptive details for the MetadataObject [getObjectProperties()]. Tools may choose to render these properties to provide the user with a better understanding of the associated MetadataObject.

• A flag [isMutable()] that indicates if this MetadataObject is mutable. Section 6.4 describes the mutable functionality in detail.

• A flag [isSelectableForImport()] that indicates if this MetadataObject can be selected for import into a ServiceDescription. If a MetadataObject is selectable then it indicates to the tool that a MetadataImportConfiguration can be created for the object and added to an existing MetadataSelection. The next section describes this process in detail.


Page 38 of 114

• A factory method [createImportConfiguration()] to create a MetadataImportConfiguration instance for the MetadataObject. The next section describes this process in detail.

6.2.3. Filtering Properties As outlined in the sections above, the EMD specification allows for filtering of MetadataObjects returned from a query, or from an expansion of a parent MetadataObject node in the MetadataTree. The configuration of this filtering is done via properties, in a PropertyGroup, which a user can configure. It is up to the discovery service provider to have correct filter properties that match the capabilities of the EIS. For example, if an EIS supports filtering based on string with wildcards, then the filtering PropertyGroup would have a string property that allows entry of wildcard strings. A discovery service provider may also wish to include additional filtering properties that don’t necessarily reflect the capabilities of the EIS, but instead offer enhanced functionality to the tool user. For performance, a provider may include properties that specify the cache size for the MetadataObjectIterator, or specify the maximum number of returned MetadataObjects from a query.

6.3. Importing Metadata Having queried and navigated a MetadataTree, the tool user must select the MetadataObjects desired for import into a ServiceDescription. This involves selecting each MetadataObject, configuring how it is to be imported into the ServiceDescription and adding this configuration to the overall selection of objects needed for the ServiceDescription. The MetadataImportConfiguration and MetadataSelection interfaces provide this functionality.

6.3.1. MetadataImportConfiguration For every MetadataObject that is to be imported, a configuration needs to be captured. This configuration defines how the MetadataObject is to be included in the generated ServiceDescription. For example, the configuration of an EIS business object may include definitions that describe whether the object is to be included for inbound or outbound interaction in the ServiceDescription. The MetadataImportConfiguration interface represents the individual configuration for each MetadataObject. In other words, for each object desired for import, the tool must create a corresponding MetadataImportConfiguration which is used to generate the final ServiceDescription . The MetadataImportConfiguration interface provides a handle to the location ID of the associated MetadataObject as well as an optional description that the tool can use to display to the user. It also provides a factory method [createConfigurationProperties()] to get any configuration properties that are required to configure the MetadataObject for import. If there are no configuration properties then NULL is returned. If there are configuration properties then the tool must render these properties to the user for configuration. After configuration, the properties are applied onto the MetadataImportConfiguration via a call to applyConfigurationProperties().

Figure 6.12: The MetadataImportConfiguration interface


Page 39 of 114

6.3.2. MetadataSelection A ServiceDescription is typically created from multiple MetadataObjects. In order to generate the description, from the collection of desired MetadataObjects, a container mechanism is needed to aggregate all the selected objects. This container is provided by the MetadataSelection interface.

Figure 6.13: The MetadataSelection interface

The MetadataSelection provides facilities to add and remove MetadataImportConfigurations to the selection, as well as retrieve the entire set of MetadataImportConfigurations that comprise the selection. There are instances when the entire selection may require extra configuration given that it is the selection that forms the end result ServiceDescription. An example may be a configuration property for a name prefix that is to be applied to all function descriptions created from MetadataObjects that represent EIS Business Objects. The factory method [createSelectionProperties()] is used by the tool to retrieve such configuration properties, if they exist. If properties do exist then the tool must render them to the user for configuration, and apply the configured properties using the applySelectionProperties() method. It is also important to note that the MetadataSelection is wholly responsible for ensuring the integrity of the selection. This includes guaranteeing that the MetadataImportConfigurations, contained within the selection, can co-exist in one ServiceDescription. For example, ServiceDescriptions can only be inbound, or outbound, but not both. Hence it is invalid for a MetadataSelection to contain a mix of MetadataImportConfigurations that represent both inbound and outbound EIS interactions. The MetadataSelection must check the integrity of the current selection within every call to the add() method. If the added MetadataImportConfiguration is not compatible with the current selection then the addition must be rejected, by throwing a MetadataImportException. To assist in the usability of the MetadataSelection, the canAdd() method is provided. This method must be used by tools before attempting to create a MetadataImportConfiguration for a selected object. The canAdd() method tests if the given MetadataObject would be compatible with the current selection. If not, then the tool knows this upfront and can spare the user from configuring a MetadataImportConfiguration for an incompatible object. The canAdd() method returns a MetadataImportConfiguration and the tool must use this import configuration if it wishes to add the MetadataObject to the current selection. In most cases the MetadataImportConfiguration returned will be identical to the one returned from the MetadataObject.createImportConfiguration() method. However there can be cases where a MetadataObject may be compatible with a current selection if, and only if, its configuration parameters are constrained to certain values. In such cases the canAdd() method can return a different MetadataImportConfiguration whose configuration properties have the constraints enforced upon them.


Page 40 of 114

An illustrative example of this can be an EIS system that allows the import of its business objects for either inbound or outbound interactions. The sequence diagram below demonstrates how a tool must add a MetadataObject to a current selection. The diagram is for illustrative purposes, hence an assumption is made that the MetadataObject can be added to the selection, and that its configuration properties do not need to be constrained.

Figure 6.14: Adding a MetadataObject to a MetadataSelection

6.3.3. MetadataObject Selection best practices. As described above, the task of selecting a MetadataObject involves first configuring it and then adding it to an existing selection. For this reason, it is not realistic for a tool to be able to implicitly select MetadataObjects, such as in cases where a parent MetadataObject is selectable for import as well as all of its children. One might expect that in such situations, selecting the parent MetadataObject would cause the tooling to implicitly select all the selectable children objects as well. For the tool to do this correctly it would need to prompt the user for configuration parameters for each child object, and do the same for all nested child objects. Furthermore, a filter may have been applied when the children were expanded. In this case, it becomes ambiguous for the tool to decide whether only the visible filtered children or all children should be implicitly included. Clearly, implicit object selection can easily become complicated for even a moderate amount of child objects. For this reason, the EMD specification mandates that all MetadataObject selection for import must be explicitly done by the tool user. In other words, if a tool encounters a parent MetadataObject whose


Page 41 of 114

children are also selectable, when the parent is selected for import then only the parent is added to the current metadata selection. If the children are desired to be included in the selection as well, then they must be explicitly added by the user. It is recommended, as a best practice, that discovery service providers always make selectable MetadataObjects not have children whom are selectable as well. This helps simplify matters for both the tool user and the tool itself. If it is required that children objects be included with the parent during selection, then the discovery service provider should include this as configuration parameters of the parent’s MetadataImportConfiguration. This can be easily achieved by either:

• having a Boolean property for each selectable child, where the user indicates if the child is to be included via the property value, or

• Using a TreeProperty to represent all the children that can be included with the parent.

6.3.4. Tool Code Sample The following code sample illustrates how a tool would invoke the discovery flow outlined in figure 6.1, using the interfaces described in the sections above: //A MetadataDiscovery instance from the EMD service provider that was //obtained by the tool environment during the bootstrap process. MetadataDiscovery metadataDiscovery; //The tool environment needs to create a tool context to pass //to the discovery service for use until a metadata connection is obtained. ToolContext toolContext = new ToolEnvironmentToolContext(); metadataDiscovery.setToolContext(toolContext); // Get the set of supported AdapterTypes. For illustrative purpose select the first one. // We also assume here that the selected adapter type supports metadata // connections AdapterTypeSummary[] summaries = metadataDiscovery.getAdapterTypeSummaries(); AdapterType adapterType = metadataDiscovery.getAdapterType(summaries[0].getId()); //Check that the AdapterType supports metadata connection types if (!adapterType.hasMetadataConnectionTypes()) { //Obviously, a real tool would //want more robust error handling. We just return here. System.out.println("This adapter type does not support metadata discovery"); return; } // Get the list of outbound connection types. For illustrative purpose select the first one. // We assume that this connection type supports metadata connections. OutboundConnectionType[] connectionTypes = adapterType.getOutboundConnectionTypes(); OutboundConnectionType aConnectionType = connectionTypes[0]; //Check that the AdapterType supports metadata connection types if (!aConnectionType.isSupportedInMetadataService()) { //Obviously, a real tool would //want more robust error handling. We just return here. System.out.println("This connection type does not support metadata discovery"); return; } // At this point the tool environment should point to see if there are // any persisted connections using the persistence mechanism. // For simplicity we will just create a new metadata connection. // To do so we first create an outbound connection configuration OutboundConnectionConfiguration connectionConfiguration = aConnectionType .createOutboundConnectionConfiguration(); //The tool environment must now get the configuration properties on the //OutboundConnectionConfiguration PropertyGroup configurationProperties = connectionConfiguration.createUnifiedProperties(); //The tool environment must render the properties and allow the user to //set the property values, then apply the set values.


Page 42 of 114

connectionConfiguration.applyUnifiedProperties(configurationProperties); // Now get a live connection for browsing the metadata tree MetadataConnection aMetadataConnection = aConnectionType.openMetadataConnection(connectionConfiguration); //The tool environment needs to create a tool context to pass //to the metadata connection for use during this discovery session, or reuse the tool //context that was set on the MetadataDiscovery. ToolContext connectionToolContext = new ToolEnvironmentToolContext(); aMetadataConnection.setToolContext(connectionToolContext); // Get a reference to the metadata tree for the connection we just // opened. MetadataTree tree = metadataDiscovery.getMetadataTree(aMetadataConnection); //Now start to query the metadata objects that are available. //First the tool must get the filter paramters that can be used. PropertyGroup topLevelFilter = tree.createFilterProperties(); //At this point the tool environment should render the filter //properties to the user and allow them to configure their search parameters // Now take the filter and apply to get the list of objects that // match it. MetadataObjectResponse response = tree.listMetadataObjects(topLevelFilter); MetadataObjectIterator iterator = response.getObjectIterator(); if (!(iterator.size() > 0)) { //The results came back empty. Get the reason why and exit. //We assume in our case that we should get returned objects, //so we consider this an error. Obviously, a real tool would //want more robust error handling. We just return here. System.out.println(response.getMessage()); return; } //Now display all the children. MetadataObject nextLevel = null; while (iterator.hasNext()) { MetadataObject businessObject = iterator.nextMetaDataObject(); // For our scenario we want to traverse into the first branch // of the tree so we store the first child for later drill-in. if (nextLevel == null) nextLevel = businessObject; // A real tool would probably add a tree node for each object // we iterate over. Here we're just printing out to System.out. System.out.println(businessObject.getDescription()); System.out.println(businessObject.getDisplayName()); //Get any display properties and show them to the user PropertyGroup displayProperties = businessObject.getObjectProperties(); } //Now get the first child and query its children. PropertyGroup childrenFilter = nextLevel.createFilteringProperties(); //Tool would render the filter properties to the user and allow //them to configure. //Now apply the filter to get the child nodes that match it. MetadataObjectResponse childrenResponse = nextLevel .getChildren(childrenFilter); MetadataObjectIterator childIterator = childrenResponse .getObjectIterator(); if (!(childIterator.size() > 0)) { //no children were returned. Get the reason why and exit. //We assume in our case that we should get returned objects, //so we consider this an error. Obviously, a real tool would //want more robust error handling. We just return here. System.out.println(childrenResponse.getMessage()); System.exit(-1); } //cycle through all of the children and select the following: // - BusinessObjects/Standard/Account


Page 43 of 114

// - BusinessObjects/Standard/PurchaseOrder // Note that a real tool environment would allow the user to // interactively select objects and add them to the the selection. Set objectLocations = new HashSet(); objectLocations.add("BusinessObjects/Standard/Account"); objectLocations.add("BusinessObjects/Standard/PurchaseOrder"); MetadataSelection selection = tree.createMetaDataSelection(); while (childIterator.hasNext()) { MetadataObject metadataObject = childIterator.nextMetaDataObject(); if (metadataObject.isSelectableForImport() && objectLocations.contains(metadataObject.getLocation())) { // Its a designated object in the tree, so we add it to the // selection. This is done by first testing if we can add it to the selection. // If the add is allowed then we use the designated MetadataImportConfiguration. MetadataImportConfiguration configuration = selection .canAdd(metadataObject); if (configuration != null) { PropertyGroup objectConfigurationProperties = configuration.createConfigurationProperties(); // display the configuration properties to the user and // allow them to configure configuration.applyConfigurationProperties(objectConfigurationProperties); try { selection.add(configuration); } catch (MetadataException e) { // The addition was rejected as it is not compatible // with the current selection e.printStackTrace(); } } } } //Now check if there are any additional properties we need to set //on the selection PropertyGroup selectionProperties = selection.createSelectionProperties(); if (selectionProperties != null) { //Show the properties to the user and allow them to configure. selection.applySelectionProperties(selectionProperties); } //Now create the service description. ServiceDescription serviceDesc = metadataDiscovery.createServiceDescription(selection); //The Tool environment should now generate a service interface from the description //using its own supported programming model. //Now that the discovery session is done we close the open connection aMetadataConnection.close();

6.4. Mutable Metadata Tree (Object Wizard) In the process of browsing the metadata tree and importing a new service, the user (or discovery service) may need the ability to modify the tree. For example, a discovery service could provide the capability to store SQL queries to JDBC EISs. These stored queries could be part of the metadata that a tool user is browsing. The discovery service could then provide the capability to add, delete, and update these queries through the tool. The ability to add, update, delete and perform other operations on the tree gives the end-user a powerful mechanism to interact with the metadata tree. It also allows discovery service providers to innovate and distinguish themselves from other providers for the same EIS. It is optional whether the discovery service chooses to support the object wizard and all the operations that can be performed. If the discovery service supports this, the tool must also support it.


Page 44 of 114

The object wizard has not been designed as a means to administer the EIS. It should be used to customize the metadata tree for developing services. To invoke the object wizard, the tool user must browse the metadata tree, select the node that needs to be modified, and select the operation that needs to be performed on it. From then onwards the tool takes control and walks the user through all the different steps needed to complete the operation. It could be envisioned that if the tool were GUI based, the tool user would browse the metadata tree just like a anyone would browse a directory structure, right click on the identified node and then select the operation from the list of operations that were displayed upon right-clicking on the node. The ability and the process by which a user edits the metadata tree are controlled by the discovery service provider. The only function of the tool is to display a generic wizard from the information provided by the discovery service. The wizard may be a simple command line tool or a GUI. If an exception is thrown by the discovery service during the process of editing the tree, the tool should assume that an irrecoverable error has occurred and should abort the edit process. Further, it should assume that the metadata tree has not changed. In the event of an exception, it is the discovery service’s responsibility to perform the necessary cleanup and return the tree to its original state. This section contains an interaction diagram that will explain the process by which a user might edit the metadata tree.

Figure 6.15: The mutable object interfaces

The package that supports the mutable metadata tree functionality is commonj.connector.metadata.discovery.mutable. This package contains the following interfaces:


Page 45 of 114

• Operation

This interface represents an operation that may be performed on a node in the metadata tree.

• OperationType This interface enumerates the different types of operations that may be performed on the node in the metadata tree. The operation types that are supported are Create, Delete, Update and NonVisible. The Create, Delete and Update operations result in a visible change to the metadata tree whereas the NonVisible operation does not result in visible changes to the tree.

• Create This operation results in the creation of a new node. This new node is a child of the node on which the operation is performed. Only one node is created by this operation. After the new node is created, it must not be added to any current iterator of its parent. See section 6.2.1 in the document.

• Delete This operation results in deleting the node on which the operation is performed. All node iterators below the deleted node should be considered invalid once the node is deleted. The iterator of the parent must not be modified and the deleted node must not be removed from the iterator of its parent.

• Update This operation results in an update of the node on which the operation is being performed.

• NonVisible This is an operation that is performed on a node that does not visibly affect it or any other node in the metadata tree. It may result in some internal changes to that node or the tree.

Only one overall type of operation can be performed by any given wizard.

• ObjectWizard This interface represents a wizard that will walk a tool user (in one or more steps) through the modification of a selected node in the metadata tree. Each step in the wizard is represented by the ObjectWizardStep interface.

• ObjectWizardStatus

This interface enumerates the different states that the object wizard may be in. The different states are START, CONTINUE and FINISH.

• START

This state indicates that the wizard is in its first step in the process of performing an operation.

• CONTINUE

This state indicates that the object wizard is in an intermediate stage in the process of completing the operation.

• FINISH

This state indicates that the object wizard has finished completing the operation. When the tool notices that the object wizard has reached this stage it must assume that no more wizard steps need to be displayed and that the wizard operation has been completed.


Page 46 of 114

• CANCEL

This state indicates that the operation has been cancelled.

• ObjectWizardStep This interface represents the individual steps in the object wizard. It contains all the necessary information that is required for a particular step. It also contains all the different actions that may be performed in that step.

• Action This interface defines an action that may be performed on an object wizard step. It is required that every object wizard step have a cancel action. This action can be used by the tool user to cancel any operation if needed.

Shown below is an interaction diagram that describes creating a new node. The interaction starts at the point that the tool user has navigated the metadata tree and located the node for which a child needs to be created. Once the node has been identified, the tool user views all the possible operations on the node and selects the create operation. Once the tool user has selected the operation, the tool walks the user through all its different steps until operation has been completed. After the operation has been completed the tool calls the completeCreateOperation method to get the node that was created. When the tool notices that the object wizard has reached the “FINISH” or “CANCEL” stage it must assume that no more wizard steps need to be displayed and that the wizard operation has been completed.


Page 47 of 114

Figure 6.16: Creating a new MetadataObject node

6.5. Tool requirements The tool must:

• Provide a bootstrap mechanism to locate the MetadataDiscovery implementation from the discovery-service.xml file of the adapter. The bootstrap process must also instantiate a new instance of this implementation using its default no-argument constructor.

• Any interaction between the tool and an EIS must originate from the implementation of the MetadataDiscovery interface.

• To perform metadata discovery, the tool must only allow the selection of AdapterTypeSummaries that support ConnectionTypes that can be used for discovery.

• A ToolContext must be set on the MetadataDiscovery implementation, however this context must only be used to report progress and log any activity that occurs in the process of creating a MetadataConnection

• The ToolContext logger, provided by the tool, must guarantee to handle standard java.util.logging.LogRecord records. The tool does not have to handle customized log records.

• Create a MetadataImportConfiguration which is used to generate the final ServiceDescription


Page 48 of 114

• If a non-null PropertyGroup is returned from any of the create property methods, then the tool must render the PropertyGroup to the user for input.

• If the discovery service supports the object wizard the tool must also support it. • Tools must call the canAdd() before attempting to create a MetadataImportConfiguration for

a selected MetadataObject.

The tool should: • If an exception is thrown by the discovery service during the process of editing the metadata tree,

the tool should assume that an irrecoverable error has occurred and should abort the edit process. Further, it should assume that the metadata tree has not changed.

6.6. Discovery service requirements The discovery service must:

• Supply implementations for all the following interfaces: o commonj.connector.metadata.discovery.AdapterType o commonj.connector.metadata.discovery.AdapterTypeSummary o commonj.connector.metadata.discovery.MetadataDiscovery

• If service discovery is supported then implementations must be supplied for the following interfaces:

o commonj.connector.metadata.discovery.MetadataImportConfiguration o commonj.connector.metadata.discovery.MetadataObject o commonj.connector.metadata.discovery.MetadataObjectIterator o commonj.connector.metadata.discovery.MetadataObjectResponse o commonj.connector.metadata.discovery.MetadataSelection o commonj.connector.metadata.discovery.MetadataTree

• If service discovery is not supported a MetadataException must be thrown from all the methods of the MetadataDiscovery implementation. The error message in this exception must indicate that service discovery is not supported by the adapter.

• Provide one, and only one, implementation of the MetadataDiscovery interface. This implementation must have a default no-argument constructor.

• Provide AdapterTypes that only return those connection types they support, and NULL otherwise. • Provide a MetadataSelection implementation that is wholly responsible for ensuring the

integrity of the selection. This includes guaranteeing that the MetadataImportConfigurations, contained within the selection, can co-exist in one ServiceDescription

• Use all the methods of the ProgressMonitor interface from the ToolContext to communicate operation progress with the tool and respond to cancellation requests.

• Always provide a cancel action for every ObjectWizard step. • If an exception occurs within the steps of the object wizard, the discovery service must perform

the necessary cleanup and return the tree to its original state before re-throwing the exception. • Only one overall type of operation can be performed by any given wizard. • The discovery service provider must maintain the different states of the object wizard.

The discovery service should:

• Provide logging and tracing output using the Logger from the ToolContext. • Provide an object wizard implementation if the corresponding EIS metadata repository supports

editing of its metadata tree. Support for object wizard functionality is optional. The ability and the process by which a user might edit the metadata tree are controlled by the resource adapter and the underlying EIS it connects to.


Page 49 of 114

• The different operations that can be performed on a node are Create, Delete, Update and NonVisible. It is up to the discovery service provider to choose which operations are supported. All, none or any combination can be supported by the discovery service.


Page 50 of 114

7. Importing into a Service This chapter specifies the service description contract between the tool and the discovery service. It discusses the contract specifying relevant details of the contract, and the responsibilities of the tool and the discovery service for this contract.

7.1. Overview Once the tool user has finished selecting objects on the MetadataTree and has added them to the MetadataSelection, it is time for the ServiceDescription to be created. The ServiceDescription creation is invoked by the tool when it invokes the discovery service’s createServiceDescription method passing the MetadataSelection as an argument. The result is a ServiceDescription which describes the metadata connection and its state, and the connection, interaction, and data for the service. The ServiceDescription will either describe an inbound or an outbound service. The Service Description is described by the interfaces in package commonj.connector.metadata.description. It is comprised of the following:

• ServiceDescription

o MetadataConnectionConfiguration

o MetadataSelectionProperties

o OutboundConnectionAdvancedConfiguration (for an outbound service)

o InboundConnectionAdvancedConfiguration (for an inbound service) o Function Description

MetadataImportConfiguration

Input DataDescription

• SchemaDefinition

• DataFile

Output DataDescription

• SchemaDefinition

• DataFile

The interfaces for the Service and Function Descriptions differ slightly for inbound and outbound in order to be consistent with the J2EE CA 1.5 specification. For example, inbound connections require an ActivationSpec and outbound connections require a ManagedConnectionFactory. Also, outbound functions require an InteractionSpec to be specified. The Data Description is identical for both inbound and outbound.

7.2. Goals The service description contract has been defined with the following goals:


Page 51 of 114

• The service description will be used either to generate the service interface and implementation, or it could be used directly by an interpretive runtime to invoke the service. The tool is allowed the choice of serialization and programming model.

• The service description will also be used by the tool to revive the MetadataConnection with its state as one mode of providing further editing support of the service.

7.3. Architecture

7.3.1. Service Description There is a base interface ServiceDescription that is extended by OutboundServiceDescription and InboundServiceDescription.

Figure 7.1: Service description

When the ServiceDescription is created, the discovery service should populate the Name and Comment fields if it can determine meaningful values. The Name field must conform to the naming conventions for classes as specified in section 6.8.2 of the Java Language Specification. The name of the service description may be edited in the tool after import. The nature of the service interface generated from the ServiceDescription is the decision of the tool. Before generating the service interface, the tool should allow the user to set a more meaningful name and description to the serialized form. The service description also contains an array of function descriptions which describe the inbound or outbound interactions between the EIS and the application server. To support editing of the service description, where the state of the metadata connection can be revived, the service description has an OutboundConnectionConfiguration which has the properties of the MetadataConnection, and a PropertyGroup of the MetadataSelection properties. The tool framework is responsible for saving the state of these objects. See section 12 for more details.


Page 52 of 114

The OutboundServiceDescription contains an OutboundConnectionConfiguration for the connection used at runtime. The InboundServiceDescription contains an InboundConnectionConfiguration for the connection used at runtime. The InboundServiceDescription also contains the fully qualified class name of the FunctionSelector and the Listener. At runtime, the FunctionSelector is used to map the inbound message to the correct function on the service description. The FunctionSelector class must be visible to the application invoking the service interface. It is recommended to package it with the resource adapter. The FunctionSelector must also have a public default constructor. The Listener interface must be implemented by the J2EE CA MessageEndpoint that will receive inbound messages (typically a message driven bean) for the inbound service. It is recommended to use the MessageListener or InboundListener interfaces. If the Listener interface is provided by the resource adapter it must be visible to the classLoader of the application. The ConnectionConfiguration also provides access to its ConnectionType. Once the tool framework has the ServiceDescription, it should check to see if the connection configuration is complete using the ConnectionType.isConnectionConfigurationComplete() method. If it is not complete then the tool framework should allow the user to edit the ConnectionConfiguration or substitute it with a persisted ConnectionConfiguration. Refer to section 5 for more details.

7.3.2. Function Description The FunctionDescription describes an inbound or outbound interaction between the application and the EIS system. There is a base interface FunctionDescription that is extended by OutboundFunctionDescription and InboundFunctionDescription. The FunctionDescription is manifested as a function or operation on the service interface.

Figure 7.2: Function description When the FunctionDescription is created, the discovery service must populate the Name field with a meaningful value. The Name field must conform to the naming conventions for methods as specified in section 6.8.3 of the Java Language Specification. The name must be unique within the service description. Function overloading is not allowed. The name of the function held in the FunctionDescription may be edited within the tool environment after import.


Page 53 of 114

The FunctionDescription contains a Comment field which describes the function. This should be populated by the discovery service if meaningful information is available from the EIS. If the information in the EIS is internationalized then the description should be returned using the locale of the tooling environment. The FunctionDescription contains the MetadataImportConfiguration of the MetadataObject that was used to create it. This is used to support editing of the FunctionDescription at a later point in time. There may be a 1 to 1 correspondence between the FunctionDescription and MetadataImportConfiguration. For example, this may occur where functions from an EIS were selected for import. There may be an N to 1 correspondence between FunctionDescriptions and a MetadataObject. For example, this may occur when EIS business objects were selected for import. In the latter case, the discovery service can optimize by reusing the same MetadataImportConfiguration object for the appropriate FunctionDescriptions. The tool can also optimize creation of the service interface by recognizing the same MetadataImportConfiguration is being reused, which can be determined if location ID of the MetadataImportConfiguration is the same. The InboundFunctionDescription contains the EIS function name. This is used at runtime to map the incoming message to this function using the FunctionSelector identified in the InboundServiceDescription. The OutboundFunctionDescription contains a properly configured EIS InteractionSpec. This is used at runtime to properly invoke this function. The FunctionDescription also contains an input and an output DataDescription.

7.3.3. Data Description A DataDescription describes a data element that can be used as a request or response payload for a FunctionDescription. The structure of the data element is described using XSD. XSD is a common canonical form to describe types, and is also supported by SDO.


Page 54 of 114

Figure 7.3: Data description

The DataDescription can contain any number of SchemaDefinition instances. A SchemaDefinition contains a XSD. The XSD in the list of SchemaDefinitions are related through includes or imports, and together describe the structure of the request or response payload. The SchemaDefinition will indicate whether it is editable, as a hint to the tool whether it should save it in a read only mode or not. It also contains the namespace of the schema, a URI location (which may be relative or absolute), and the contents of the schema. If the URI location is absolute then the discovery service must guarantee access to it, and the contents of the schema will be null, since tooling will not need to serialize it. The SchemaDefinitions returned by the DataDescription may use relative or absolute paths for its imports and includes. For relative paths, the referenced schema must be returned in the array of SchemaDefinitions. The relative URI must be a relative-path reference, as described in RFC 2396. The root of the tree for relative addressing of the URI is supplied by the tool. For absolute paths, only the first absolute SchemaDefinition should be included in this array, and its contents must be set to null. Schema definitions that are imported or included by the absolute SchemaDefinition should not be included in the array list. Some example URI paths are:

• http://www.abc.com/example/Customer.xsd (absolute path) • example/Customer.xsd (relative-path reference) • ../customer/Address.xsd (invalid relative-path reference since it exceeds the root supplied by the

tool). • /customer/Phone.xsd (invalid, since this relative reference is an absolute-path reference, and not a

relative-path reference)

http://www.abc.com/example/Customer.xsd


Page 55 of 114

Figure 7.4: SchemaDefinition examples

The DataDescription specifies the data element structure using the QName for the global complexType that describes it. The DataDescription also contains an optional descriptive comment populated from information in the EIS if it is available. This is a locale specific object that should be separated and translated in the EIS, and retrieved using the locale of the tool environment. A DataBinding represents mapping between the data in the client application format and the data in the target service format. It is manifested as a class that maps from a DataObject to an EIS native object, or as a CCI Record that also provides the client application format. The DataDescription can optionally contain an array of DataFiles. These are auxiliary files that can be used by the DataBinding to perform data transformation (between DataObjects and EIS native objects). A DataFile provides a relative URI location for saving the data file, and a byte array for its contents. The constraints of the location on the SchemaDefinition apply to the location on the DataFile.


Page 56 of 114

The DataDescription must also contain the fully qualified class name of the DataBindingGenerator or the generic DataBinding. More information about DataBinding and DataBindingGenerator is found in section 9.3.

7.3.4. Data Binding Generator The DataBindingGenerator is a factory that defines a single factory method called generateDataBinding. This returns an array of DataBindingDescriptions.

Figure 7.5: DataBinding Generator

Exactly one of the DataBindingDescriptions must indicate it is a root. A root DataBindingDescription represents the DataBinding used with the input or output DataObject, or is the input or output CCI Record. The DataBindingDescription also will indicate if it is a DataBinding and so should be used with DataObjects (isDataBinding() == true) or is a CCI Record (isDataBinding() == false) and should be surfaced directly on the service interface. The array of DataBindingDescriptions must be homogenous, in that it should only return DataBindings or CCI Records, not a combination. The DataBindingDescription will also return the fully qualified class name and the complete source contents of the class. Generated source for a DataBinding class must not depend on, at compile-time or runtime, any class from a jar or component not listed below.

o JDK 1.4 or later (depends on the target runtime environment) o J2EE CA 1.0/1.5 o SDO 2.0 o EMD 1.0 o the libraries of the resource adapter

The fully qualified class name of the DataBinding must be unique. To reduce the chance of collisions, it is recommended that the DataBindingClassName in the DataBindingDescription be derived from the schema following the naming rules in SDO 2.0. If the name of the service data object would be "abc.Customer" then the name of the DataBindingClassName should be "abc.<"binding">.CustomerDataBinding". The <"binding"> name must be a valid token of a Java package, and should be meaningful, such as the EIS system name.


Page 57 of 114

7.4. Tool requirements The tool must

• Either generate the service interface and implementation, or use it directly by an interpretive runtime to invoke the service. The tool is allowed the choice of serialization (how the service description is rendered into a runnable or storable form) and programming model.

• Keep the appropriate information from the service description so that it can revive the MetadataConnection with its state as one mode of providing editing support of the service.

• Generate the J2EE CA MessageEndpoint (commonly as a message driven bean) with the specified Listener interface for the inbound service.

• If the SchemaDefinition specifies read only mode then the tool must save the XSD in read only mode.

• Save any specified DataFiles in the specified relative location. • If the DataDescription specifies a DataBindingGenerator then invoke it after any service updates

and prior to invoking the service. The tool should

• Prior to generating the service interface, allow the user to set a more meaningful name and description for it.

• Check to see if the connection configuration is complete using the ConnectionType.isConnectionConfigurationComplete() method. If it is not complete then the tool framework should allow the user to edit the ConnectionConfiguration or substitute it with a persisted ConnectionConfiguration.

• The tool should also optimize creation of the service interface, for service editing, by recognizing the same MetadataImportConfiguration is being reused for function descriptions

7.5. Discovery service requirements The discovery service must

• Generate a ServiceDescription which describes the metadata connection and its state, and the connection, interaction, and data for the service as derived from the metadata selection.

• If a service name is specified, it must conform to the naming conventions for classes as specified in section 6.8.2 of the Java Language Specification.

• Provide a FunctionSelector class which is visible to the application invoking the service interface (in RAR archive or other location visible to a ResourceAdapter instance running in the server). It is recommended to package it with the resource adapter. The FunctionSelector must also have a public default constructor.

• For function descriptions, the discovery service must populate the Name field with a meaningful value. The Name field must conform to the naming conventions for methods as specified in section 6.8.3 of the Java Language Specification. The name must be unique within the service description. Function overloading is not allowed.

• Provide an XSD (within a SchemaDefinition and DataDescription) which describes the request or response payload for a function.

• Must indicate if the SchemaDefinition is editable, as a hint to the tool whether it should save it in a read only mode or not.


Page 58 of 114

• If the URI location of the XSD is absolute then the discovery service must guarantee access to it, and the contents of the schema will be null, since tooling will not need to serialize it.

• The SchemaDefinitions returned by the DataDescription may use relative or absolute paths for its imports and includes. For relative paths, the referenced schema must be returned in the array of SchemaDefinitions. The relative URI must be a relative-path reference, as described in RFC 2396. The root of the tree for relative addressing of the URI is supplied by the tool. For absolute paths, only the first absolute SchemaDefinition should be included in this array, and its contents must be set to null. Schema definitions that are imported or included by the absolute SchemaDefinition should not be included in the array list.

• The DataDescription specifies the data element structure using the QName for the global complexType that describes it. It’s namespace must not be null.

• The DataDescription must also contain the fully qualified class name of the DataBindingGenerator or the generic DataBinding.

• Exactly one of the DataBindingDescriptions must indicate it is a root, which represents the DataBinding used with the input or return DataObject, or is the input or output CCI Record. The DataBindingDescription also will indicate if it is a DataBinding (isDataBinding() == true) and so should be used with DataObjects or is a CCI Record (isDataBinding() == false) and should be surfaced directly on the service interface. The array of DataBindingDescriptions must be homogenous, in that it should only return DataBindings or CCI Records, not a combination. The DataBindingDescription will also return the fully qualified class name and the complete source contents of the class.

• Must attempt to provide unique class names for the DataBinding. To reduce the chance of collisions, it is recommended that the DataBindingClassName in the DataBindingDescription be derived from the schema following the naming rules in SDO 2.0. If the name of the service data object would be "abc.Customer" then the name of the DataBindingClassName should be "abc.<"binding">.CustomerDataBinding". The <"binding"> name must be a valid token of a Java package, and should be meaningful, such as the EIS system name.

The discovery service should

• Populate the Name and Comment fields of the service description if it can determine meaningful values.

• Use the MessageListener or InboundListener interfaces. • Populate the FunctionDescription Comment field if meaningful information is available from

the EIS. If the information in the EIS is internationalized then the description should be returned using the locale of the tooling environment.

• Populate the descriptive comment in the DataDescription from information in the EIS if it is available. This is a locale specific object that should be separated and translated in the EIS, and retrieved using the locale of the tool environment.

• Provide DataFiles if the DataBinding needs extra information for transforming data.


Page 59 of 114

8. Property Groups As outlined throughout this specification, there are many points of interaction between a discovery service provider and the tool user. This interaction usually involves collecting user input to configure various components within the discovery service, or its generated artifacts. This user input is often more complex than just setting simple property values on a JavaBeanTM, and typically requires some type of interactive feedback as input is gathered. The tool is the primary interface for the user and as such it must act as the intermediary between the service provider and the tool user during user input interaction. For the tool to be able to do this, a mechanism must exist by which service providers can declare the user input required. Tools are then responsible for using this declaration to render the appropriate user interface and collect the user input. Because the user input is non-trivial, this declarative mechanism must support complex definitions. Some current technologies exist today that support this, such as HTML scripted forms, XHTML, TCL, etc. However these technologies require that tools operate in a specific GUI environment, such as a Web browser for HTML forms. This is too restrictive for tools since most of them operate in their own proprietary graphical environment, which may involve Wizards or Editors. As a result, the EMD specification defines a set of property descriptor interfaces that service providers must use to declare the user input required. These interfaces are rich enough to define very complex and interactive user input requirements, while also offering tools the flexibility of displaying the user interface in whatever form best suits their graphical system. These interfaces are located in the commonj.connector.metadata.discovery.properties package, and must be implemented by service providers. Figure 8.1 below illustrates the core set of interfaces used to declare required user input:


Page 60 of 114

Figure 8.1: Core Property Group interfaces

Each item of user input is defined as a PropertyDescriptor. PropertyGroups are logical aggregations of PropertyDescriptors, and Property instances represent actual property values that are set, or viewed, by the tool user. The PropertyType interface provides the mechanism to provide detailed descriptive information on the nature of a Property instance. Finally, a PropertyChangeListener interface provides the tool environment with an observer pattern implementation to listen to various changes occurring on properties it has rendered to the tool user. The details of the changes are captured via PropertyChangeEvents.

8.1. Property Descriptors

Figure 8.2: The PropertyDescriptor interface


Page 61 of 114

The PropertyDescriptor is the base interface that all user input items must implement. It provides the tool with a common view of all input items. The PropertyDescriptor provides:

• A locale sensitive display name for the property [getDisplayName()]. Tools must use this name when displaying the property to the user.

• A locale sensitive description for the property [getDescription()]. Tools should use this to provide additional descriptive information to the user. For example, this could be provided as part of a help pop-up for the property field.

• A unique string identifier for the property [getName()]. This identifier must be unique within the set of properties encapsulated in a PropertyGroup. The identifier is used to lookup and retrieve the property at any point in time. This identifier is intended for internal use only within the tool and should not be exposed to the tool user.

• The ability to register, and un-register, property change listeners. Tools will likely use this to register listeners for each property they render. This way, the UI will be able to respond and properly reflect the current state of the property.

• A flag to indicate if the property is enabled [isEnabled()]. Service providers can use this flag to dynamically activate, and de-activate, properties based on the state of the user input interaction. Tools will be made aware of changes in this flag via PropertyChangeEvents, and they are responsible for indicating changes to the user. For example, a tool environment can use a grayed out property field to indicate that a property has been disabled.

• A clone() method, to allow the service provider to implement any deep copying, if required, when cloning a property. Tools will likely choose to keep multiple copies of a property descriptor active. One example would be for caching purposes, to increase the responsiveness of the tool’s user interface when rendering property descriptors.

8.2. Property Groups

Figure 8.3: The PropertyGroup interface

When providing property descriptions, service providers will likely desire to logically group similar properties together for better usability. An example would be the grouping of user authentication properties (user name, password, etc.) separate from connection properties (host name, IP address, port number, etc.) on a connection configuration. The PropertyGroup allows for this logical grouping of properties. The PropertyGroup also acts as the top level container for any user input declaration. In other words, whenever user input is required the tool obtains the declaration in the form of a populated PropertyGroup (for example: MetadataImportConfiguration.createConfigurationProperties()). The PropertyGroup can contain nested PropertyGroups as well as other PropertyDescriptors such as Property or TreeProperty instances. All PropertyDescriptors can be looked up based on their string identifiers using the getProperty() method.


Page 62 of 114

8.3. Properties

8.3.1. The Property Interface

Figure 8.4: The Property interface

The Property interface represents a property descriptor whose physical value can be set and retrieved by the tool user. Any PropertyGroup declaration must include Property instances since they ultimately hold the data values supplied by the tool user as part of the user interaction. The Property interface provides the following:

• A flag [isSet()] that indicates if the property value has been set. This can be done either by the end user or automatically by the tool. For a TreeProperty, or TableProperty, this flag indicates if any change has occurred from the property’s original state. For example, a table cell value being changed.

• A method to remove any set value on the property and restore it to its default state [unset()].This will cause the isSet() to return false. If the property is a multi valued property then this has the effect of clearing the contents of the property.

• A flag [isValid()] that indicates if the current value held by the property is valid. A property's value may initially be valid. However as a result of events occurring over time, or other property value settings, this initial value may become invalid. For all properties, this method must only return true if the property has been set with a valid value, or if the property's default value is valid. Required properties are identified using the PropertyType.isRequired() method. For a NodeProperty this method must only return true when the configuration properties of the node, as well as all its children, are all valid. It is up to the implementation to decide whether the configuration properties must always be valid, or only valid when the NodeProperty is selected. For a TableProperty this method must only return true when all the cells within the table are valid.

• A locale sensitive validation message that indicates why a property value has become invalid. This method should only be called if isValid() returns false. Tools can use this message to inform the user of why the property value got invalidated and thus offer a better understanding on how to correct the situation.

Before a tool environment ends a user interaction session it must guarantee the following:

• For every required Property, the property must be set and contain a valid value. • For every non-required Property, the property must contain a valid value if it the property has

been set by the tool user. If these two conditions are not met the tool is responsible for not permitting the user interaction to end until the situation is rectified.


Page 63 of 114

8.3.2. The PropertyType Interface

Figure 8.5: The PropertyType interface

To properly display a Property, tools must have detailed descriptions of each property’s nature. This description is provided by the PropertyType interface. Each Property must have at least one PropertyType instance associated with it. The PropertyType provides the following property details:

• The Java type represented by the property [getType()]. All primitive types are represented by their Object wrappers. For example: int is wrapped by java.lang.Integer.

• A flag [isHidden()] that indicates if the property is hidden. A hidden property is one that is not intended to be visible to the tool user to manipulate. An analogy is hidden fields on an HTML form. Tools should never render hidden properties in their UI interfaces.

• A flag [isReadOnly()] that indicates if the property is a read only one that must not be set or altered.

• A flag [isExpert()] that indicates if the tool user should use care when setting values on the property. This flag can be used as a hint for tools to hide the property and only show it as an advanced property that is available if the UI is in advanced editing mode.

• A flag [isPrimitive()] that indicates if the property is a primitive type. This is only applicable if the Java type of the property is one of the primitive type object wrappers. For example: java.lang.Integer.

• A flag [isSensitive()] that indicates if the property contents should be displayed in a obfuscated manner. Password properties are an example of this. Sensitive properties must not have their contents displayed in plain text, and must be obfuscated in some way to avoid being copied. Consumers of sensitive properties must never persist the values without taking appropriate security measures, such as providing a warning message that the sensitive properties will be saved in clear text, or alternatively encrypting the properties.

• A flag [isRequired()] that indicates if the tool user must set a value for this property. Tools are responsible for ensuring that all required properties are set with valid values before ending the user input interaction. This test can be done by calling the isValid() on the associated Property. Service providers must define a property as required if one cannot rely on a default value being valid for all situations.

• The default value for the property [getDefaultValue()]. The default value must be an instance of the same Java type returned from the getType() method.

• An array of valid values that can be set on this property [getValidValues()]. This array is null if there are no recommended values for the property.


Page 64 of 114

• An array of the valid String values that can be set on this property [getValidValuesAsStrings()]. The string values returned must be semantically equivalent to the object instances they represent. In other words, the object instance, and its state, must be re-creatable using the string value. This method’s behavior is identical to getValidValues(). This method is particularly useful for tools as in most cases they will be getting user input in the form of string values entered using a keyboard.

• A flag [isValidValuesEditable()] that indicates whether the list of valid values returned from getValidValues(), or getValidValuesAsStrings(), are the only possible set of values for the property. In other words, can values other than the set of recommended values be used to set on the property? This information can be used by tools to decide whether to show the property as an editable combo box or a non-editable one for example.

8.4. Single Typed Properties As mentioned above, every Property instance must have at least one PropertyType associated with it. The most common case is where only one is associated since this corresponds to a property that maps to a single Java type. Such properties are defined using the SingleTypedProperty interface.

Figure 8.6: The SingleTypedProperty interface

It is possible to have properties that map to more than one Java type, such as data union. However, such properties are outside the current scope of the EMD specification. There are two possible flavors of a SingleTypedProperty:

1. A SingleTypedProperty that can only hold a single value. This would be a property that maps to a single instance of the associated Java type.

2. A SingleTypedProperty that can only hold a multiple value. This would be a property that maps to a collection, or an array, of instances of the associated Java type.

These two flavors are defined using the SingleValuedProperty and MultiValuedProperty interfaces respectfully.

8.4.1. The Single Valued Property Interface


Page 65 of 114

Figure 8.7: The SingleValuedProperty interface

Since the SingleValuedProperty maps to a single instance of a Java type, it has simple setter and getter methods to access the value of the associated type. The interface also provides for string based accessors to the value. The string value used must be semantically equivalent to the complete object instance it represents. In other words, the object instance, and its state, must be re-creatable using the string value. These extra accessors are provided as a convenience for tools to be able to set, and get, the property values easily within their UI layer. Properties may place limitations on what values can be set as part of their internal validation. In particular, some properties may refuse to set null values, while others will impose restrictions on the type of values that may be set. A MetadataException must always be thrown in cases where the value specified was refused. Ideally, the message field of the exception should indicate the reason for refusal.


Page 66 of 114

8.4.2. The Multi Valued Property Interfaces

Figure 8.8: The multi valued property interfaces

Since the MultiValuedProperty maps to a collection of instances of the associated Java type, it provides accessor methods that are identical to a java.util.List. It additionally provides string based accessors to match the tooling convenience of the SingleValuedProperty. MultiValuedProperty is defined to have no limit on the amount of instance values it can hold. For the cases where the size of allowed instance values is known to be fixed the BoundedMultiValuedProperty is provided. This interface identifies the allowable limit [getBoundedSize()] in addition to a flag [isAllRequired()] that indicates if tools must completely fill the property with value instances. Similar to the SingleValuedProperty, multi valued properties may place limitations on what values can be set as part of their internal validation. A MetadataException must always be thrown in cases where the value specified was refused.

8.5. Custom Properties Some user input is not as simple as setting instances, or collections of instances, on a Java type. An example of this is the entry of data cells in a relational database table, or the selection of nested directories to include from a specific file system. While it is possible to model these user inputs as a series of complex interactions between single and multi valued properties, it is much simpler to designate dedicated custom interfaces that tools must recognize. The EMD specification defines two custom property interfaces; the TreeProperty and the TableProperty.


Page 67 of 114

8.5.1. Tree Properties The TreeProperty is used to model user input where the user must select nodes from within a tree structure. An example is the selection of files to include from a file system hierarchy. Graphical tools would likely represent such properties as a check box tree. A TreeProperty is composed of a hierarchy of NodeProperty instances. The hierarchy is traversed by calling the getChildren() method on each NodeProperty. Each NodeProperty represents a selectable item in the tree. Hence each NodeProperty provides accessors to its selected state [isSelected() , setSelected()]. Additionally, each node may also have configuration properties that can be applied. As with all other property definitions, these are retrieved and applied as a PropertyGroup instance. The root of the NodeProperty hierarchy is obtained via the getRoot() method. For cases where the root is just a place holder that should not be displayed, the showRoot() method must return false.

Figure 8.9: The tree property interfaces

8.5.2. Table Properties The TableProperty can be used to model data entry into cells of a relational database table. The TableProperty is composed of a set of ColumnDescriptor instances and a matrix of single valued properties. Each ColumnDescriptor provides the description of the data type allowed within its associated column. The description is supplied via a PropertyType. The single valued property instances represent the data values for each row in the column. The description, and value, of each SingleValuedProperty must match that of the ColumnDescriptor for the column it is within.


Page 68 of 114

Figure 8.10: The table property interfaces

8.6. Property Change Events Service providers who supply PropertyGroup instances will likely have complex interactions occurring between the properties within each group. For example, as one property value changes it may trigger value changes in other properties, or may cause other properties to become disabled. Tools must be able to recognize these changes and properly convey them to the tool user. The EMD specification provides an observer pattern mechanism by which tools register listeners on each PropertyDescriptor. Listeners are notified of changes via PropertyChangeEvents. The PropertyChangeEvent class extends the base java.beans.PropertyChangeEvent. It provides a richer set of property change event types. Service providers must fire PropertyChangeEvents for all the supported property change types, and are also responsible for delivering the events to every registered listener. The table below details the content of the PropertyChangeEvent for each event type:


Page 69 of 114

Event Type Event Description

Event Source New Value Old Value

PROPERTY_VALUE_CHANGE Fired when the value of a single valued property changes

SingleValuedProperty The new current value of the property

The old value of the property

PROPERTY_VALUE_CHANGE Fired when the value of a multi valued property changes.

MultiValuedProperty The new object array of property values

The old object array of property values

PROPERTY_ENABLE Fired when a property descriptor becomes enabled.

PropertyDescriptor null null

PROPERTY_DISABLE Fired when a property descriptor becomes disabled.

PropertyDescriptor null null

PROPERTY_VALUE_VALID Fired when a property value becomes valid.

Property null null

PROPERTY_VALUE_INVALID Fired when a property value becomes invalid.

Property null null

PROPERTY_VALID_VALUES_CHANGE Fired when the set of valid values for a property change.

Property The new array of recommended property values

The old array of recommended property values

PROPERTYGROUP_ADD_CHILD Fired when a property descriptor is added to a property group.

PropertyGroup The child property descriptor that was added

null

PROPERTYGROUP_REMOVE_CHILD Fired when a property descriptor is removed from a property group.

PropertyGroup null The child property descriptor that was removed

PROPERTYGROUP_REMOVE_ALL Fired when all the contents of a property group are removed.

PropertyGroup null The old array of property descriptors that were part of the property group.

PROPERTYGROUP_REPLACE_ALL Fired when all the contents of a property group are replaced.

PropertyGroup The new array of property descriptors that are part of the property group.

The old array of property descriptors that were part of the property group.

TREE_PROPERTY_SELECTED

Fired when a node property is selected.

NodeProperty Boolean.TRUE Boolean.FALSE

TREE_PROPERTY_DESELECTED

Fired when a node property is deselected.

NodeProperty Boolean.FALSE Boolean.TRUE


Page 70 of 114

Figure 8.11: The property listener interfaces

8.7. Tool requirements A tool must

• Only surface a PropertyDescriptor’s display name to the user. The unique string identifier must be used to lookup and retrieve a PropertyDescriptor at any given time but it is intended for internal use and must not be exposed to the user.

• Register property change listeners for each PropertyDescriptor it renders to the user. These change listeners are responsible for listening to changes occurring to the PropertyDescriptor and reflecting those changes in the rendered UI.

• Ensure the following conditions are met for each PropertyDescriptor rendered: o For every required Property, the property must be set and contain a valid value. o For every non-required Property, the property must contain a valid value if it the property

has been set by the user. o If these (above) two conditions are not met the tool is responsible for not permitting the

user interaction to end until the situation is rectified. • Ensure that sensitive properties must not have their contents displayed in plain text, and must be

obfuscated in some way to avoid being copied. • Never persist the values of sensitive properties without taking appropriate security measures, such

as providing a warning message that the sensitive properties will be saved in clear text, or alternatively encrypting the properties.


Page 71 of 114

8.8. Discovery service requirements The discovery service must:

• Provide a unique string identifier for each PropertyDescriptor [getName()] a set of properties encapsulated in a PropertyGroup.

• Ensure that each Property must have at least one PropertyType instance associated • Throw a MetadataException in cases where the value being set on a property is refused. Ideally,

the message field of the exception should indicate the reason for refusal.


Page 72 of 114

9. Data Handling

9.1. Data programming model The emerging data model for service-oriented architectures is SDO [2]. EMD supports SDO 2.0 as the preferred data programming model for J2EE CA applications. The tool takes a data description generated by the discovery service and provides appropriate service data object (SDO) DataObject implementations for them. The tool may choose to provide a generic implementation or to generate a strongly-typed implementation based on the data description. At run time, marshalling the input DataObject to their internal data format and un-marshalling a response from their internal data format into a DataObject must occur. The marshal and un-marshal facility is embodied in an object called data binding. In some cases it may not be appropriate to use a service data object. In these cases, the DataBindingGenerator should detect the requirement (from information in the data meta-model) to generate CCI Record and return a CCI Record instead of a data binding. The tool is then responsible to use the CCI Record.

9.2. Data meta-model The canonical model for input and output data types is XML schema definition (XSD). This model allows for rich editing of the types and their application-specific information in the model using XSD editors. SDO supports DataObjects generated from XSD. The form for data when a discovered service is imported is described in section 7.3.3 . How to support editing of application-specific information is described in section 9.4 .

9.3. Data Bindings

A data binding represents the mapping between the SDO DataObject in the service interface client and the native format of the data in the EIS. The data binding functionality itself does not depend on the ‘direction’ of the data and is applicable to the service invocation arguments as well as results for both inbound and outbound communication. Data binding interfaces are presented in the following figure.


Page 73 of 114

Figure 9.1: DataBinding interfaces

In most cases, the format of data, understandable by the service interface client is represented by the Service Data Object (SDO) and it is assumed that clients invoking a service use SDO for arguments and results. The other case supported by EMD is described in the CCI Record section later in this document.

The DataBinding interface is the basic data binding interface. It expresses the service client or application view of the data and allows the client to set the service arguments and retrieve service results as SDO

This specification does not make any assumption about the native data format required by the service implementation. This format depends on the EIS system and the interface of the resource adapter providing access to the EIS.

9.3.1. Data Bindings for Outbound Services If the EIS is accessible through the resource adapter supporting CCI, the data binding needs to be able to present the data in the resource adapter client view, as a CCI Record.

The RecordDataBinding interface, shown below, extends the basic interface and adds to it the javax.resource.cci.Record to support CCI.

If the data binding is to be used with the adapter supporting CCI and implementing the execute method with input and output1, it must implement this interface. The input and output data bindings will be passed to the execute method of the Interaction during invocation.

1 The adapter implementation of the supportsExecuteWithInputAndOutputRecord method of the javax.resource.cci.ResourceAdapterMetaData interface returns value of true.


Page 74 of 114

The details of using data bindings at runtime for outbound services is presented in section 11.2.

It is important to note that the specification does not define or dictate any interface to be used by the resource adapter to access data binding and retrieve its contents. This is consistent with the J2EE Connector Architecture specification which only defines the adapter client view of the data, the CCI Record, but does not identify the adapter view of data leaving it to the adapter. In practice, this leads to the data binding implementation providing the ‘adapter view’ of its contents by implementing the adapter specific interface.

For example if the resource adapter expects all arguments to the execute methods to implement the following EISRecord interface

public interface EISRecordDataBinding {

public String getRecordAsString();

public void setRecordFromString(String stringRecord);

}

The implementation of the data binding passed to the execute method (RecordDataBinding) would also implement this interface.

The implementation of the data binding is outside the scope of this specification and is left entirely to the data binding provider.

The RecordDataBinding interface is not sufficient if the resource adapter supports the input only2 variant of the execute method of the J2EE CA Interaction interface. The reason is that the input only execute method creates and returns the ‘native’ result of the interaction as the CCI Record, unlike the other execute signature which has both input and output records supplied by the invoker. The returned record is not necessarily a data binding and therefore has to be passed to the data binding implementation class. Only after that can it be converted to the Data Object and returned to the client.

This functionality is provided by the RecordHolderDataBinding interface presented below. If the adapter supports the input only variant of execute, the data binding must implement this interface.

This interface allows a service implementation to retrieve the implementation of the CCI Record from the data binding and pass it to the execute method. The returned result of the execute method is set on the data binding which then can be used by the client to retrieve SDO (via getDataObject).

If the Resource Adapter supports the input only variant of the execute method, the Data Binding provider has to implement the RecordHolderDataBinding interface.

9.3.2. Data Binding for Inbound Services

For the inbound service invocation, the data binding must implement the RecordHolderDataBinding interface.

There are two different cases for the endpoint implementation that affect data binding requirements. The endpoint can either implement listener interfaces defined in the Connector Architecture and EMD (javax.resource.cci.MessageListener and InboundListener), later called standard interfaces, or a

2 The adapter implementation of the supportsExecuteWithInputRecordOnly method of the javax.resource.cci.ResourceAdapterMetaData interface returns value of true.


Page 75 of 114

custom interface specified by the resource adapter. This affects what is passed to the listener when the adapter invokes the endpoint: a CCI Record or an arbitrary list of arguments of length zero or more. The data bindings for these two cases are described below. Example code for these two cases is shown in section 11.3.

For the standard interfaces the argument is a Record and it can be set directly on the data binding, which then is used to create the argument for the invocation target, analogous to the outbound case with input only execute method. If the return value is required, it is created by the data binding and returned from the onMessage listener method.

If the resource adapter uses a custom listener interface, the RecordHolderDataBinding interface is not sufficient. The data binding expects the CCI Record representation of the adapter native data but the listener has an arbitrary list of arguments of any type. An interface which supports packaging an arbitrary set of arguments as a CCI Record is required. Such interface, an InboundNativeDataRecord interface is presented on the next figure.

Figure9.2: The InboundNativeDataRecord interface

An arbitrary number and types of arguments to the listener can be set on this interface, as the Object array. Its implementation, a Record, can then be set on the RecordHolderDataBinding interface thus passing all the listener arguments and allowing the data binding implementation to retrieve arguments and create SDO.

The resource adapters that do not support standard listener interfaces must support this interface. The data binding provided for such an adapter must recognize the CCI Record argument passed to it, to be an implementation of the InboundNativeDataRecord and containing all the listener arguments.

When the interface is used to return results to the resource adapter, the data binding implementation sets the return value analogously to the other direction, as an element at index 0 in the array.

9.3.3. Generic and Generated DataBindings

A discovery service must provide a generic data binding or a data binding generator. This is referenced in the DataDescription that describes an input or output argument to a function description.

The DataBinding generator can generate both data bindings and CCI Records. In general it is preferred for the DataBinding generator to generate a DataBinding so that a service DataObject can be used. In some cases better support may be had from a CCI Record. A possible example is when a large audio or video file is to be streamed. It is up to the DataBinding generator to determine when data bindings are not preferred and a CCI Record must be generated.

When a DataBinding generator is specified the tool is responsible for generating the DataBinding. The tool is also responsible to provide a generic implementation or to generate a strongly-typed implementation of the service data object based on the XSD defining the input or output argument. If the


Page 76 of 114

DataBinding generator generates a CCI Record the tool and runtime is responsible for using it in place of a service data object. It is required that the DataBindingGenerator and generic DataBinding have a public default constructor and are visible to the classLoader of the resource adapter. Data bindings and customer applications can use SDO 2.0’s DataFactory to instantiate DataObjects. An example is provided below.

DataObject purchaseOrder = DataFactory.INSTANCE.

create(“http://www.mycompany.com”, PurchaseOrderType");

purchaseOrder.setString("orderDate", "1999-10-20");

}

At runtime, if a generic data binding is used it will need to access application specific information to be able to map from the DataObject to the EIS native object, and back. SDO 2.0 provides the commonj.sdo.helper.XSDHelper with the following two utility methods:

• String getAppinfo(Type type, String source); Returns the content of the appinfo declared for this Type and source. The content inside the appinfo tag is returned as a string. The appinfo start and end tags are not returned. If more than one appinfo with the same source is declared on the same Type their contents are concatenated.

• String getAppinfo(Property property, String source); Returns the content of the appinfo declared for this Property and source. If the property is defined by ref= the appinfo of the referenced element or attribute is included. The content inside the appinfo tag is returned as a string. The appinfo start and end tags are not returned. If more than one appinfo with the same source is declared on the same Property their contents are concatenated.

When transforming an EIS native object to a data object, the resource adapter must have support for the generic data binding to be able to determine the data object to instantiate. For example, it may do this by constraining the name of the data object to match the name in the EIS native object, or provide a mapping table that the user can configure.

9.3.4. DataBindingGenerator The DataBindingGenerator is supplied by the discovery service. It is used to generate either

• a DataBinding which can be used to transform a SDO to an EIS native object, and vice versa • a CCI Record, which is the Java representation of a data structure used for input, or output, to an

EIS function. The tool is responsible for invoking the DataBindingGenerator.generateDataBinding() method, when the DataDescription provides a DataBindingGenerator class name. It passes as arguments the QName of the input or output complexType and the URL of its schema. The DataBindingGenerator implementation is then responsible for loading the schema, including resolving any schema imported or included. It then finds the complexType and by looking at it or annotations in the schema determines if it should be generating DataBindings or CCI Records. The array of returned DataBindingDescriptions must be consistent, in that it may only contain DataBindings or only CCI


Page 77 of 114

Record, not a mix. Each DataBindingDescription element will contain a DataBinding or a CCI Record.

9.4. Editing support Types are described using XSD. But the XSD as imported from an EIS may have names that are not descriptive. The SDO interface used by the service client is generated using the XSD, as described by SDO 2.0. Editing support is necessary to allow the declaration names to be renamed so a developer can easily work with the SDO. The annotations in the XSD that the DataBindings use to convert the DataObject to a native object may not be complete. For example, the annotations may be required to describe field lengths, byte order, etc. for a data field. Not having complete annotation information in this case makes runtime data transformations impossible. Therefore, there is a requirement to be able to edit annotations. XSD provides the appInfo tag for providers to describe application specific information. The format of annotations is proprietary to the discovery service. The discovery service must contribute schema that describes the contents of annotation appInfo it contributes so that the tool can generically support editing and validation of application specific information in appInfo tags. These schema are called ASI schema. The provided schema must describe the application specific information that can occur on a complexType, element, or attribute. There are two notions of anchor points for appInfo annotations.

• The first being able to anchor o application specific information schema to complexTypes, o application specific information schema to elements, and o application specific information schema to attributes.

• The second being able to anchor the above set of schema to a business object schema. A set of schema that applies to a business object may have more than one application specific information schema for complexTypes, elements, or attributes. For example, there may be two application specific information declarations for what can be stored on elements. An enterprise information system may have more than one set of application specific information schema. For example, the application specific information may differ when an EIS supports accessing different kinds of services such as functional access versus business object access. A business object schema may apply to more than one enterprise information system. The instances of global element declarations defined in ASI schema appear as annotations on the business object. The framework does not mandate any structure or contents of the types pertaining to global elements defined in ASI schema. There are three types of schema involved. Refer to Appendix B .

• The first is the asiSchema, provided by this specification, which describes how to anchor EIS schema declarations for appinfo into a business object schema.

• The second schema is the application specific schema, supplied by a discovery service. This schema describes the format of the ASI that can be used in a business object schema.


Page 78 of 114

• The third schema is the business object schema returned in the DataDescription describing an input or output argument. It describes the business object in the EIS, specifies the ASI set that applies, and contains EIS ASI instances.

These schemas are shown in the picture below with a short description of their contents.

9.4.1. ASI Schema The asiSchema specifies the syntax of the two anchor points:

• Anchor point 1 to be used in EIS schema: To identify which global element declarations in ASI schemas can be used as annotations on local/global element, complex types and attributes declarations in business object schema.

• Anchor point 2 to be used in the business object schema: It specifies which ASI schemas should be used to support editing and validating of ASI.

Figure 9.3: ASI Schemas

9.4.2. EIS Schema ISV or EIS providers have to annotate the global element declarations with an instance annotationType element declaration defined in the asiSchema.xsd schema. This annotation provides an anchor point to the framework to determine and validate which

• Global element declaration defined in the EIS schema can appear as annotations on local or global element, complex type and attribute declarations in the business object schema.

• Validate the contents of annotations (i.e. instances of global element declarations) against the ASI schema.

All annotations within the appinfo tag are disambiguated with the source attribute tag set to namespace URI of the annotating schema. The EMD appinfo source attribute value must be set to source=”commonj.connector.asi”.


Page 79 of 114

9.4.3. Business Object Schema The schema declaration in the business object schema has to be annotated with global element declarations with an instance annotationSet element declaration defined in the asiSchema.xsd schema provided in the Appendix. This annotation provides an anchor point to the framework to determine

• Namespace URI of the ASI schema

• Optionally the location where ASI schema can be found. Implementations could have facility to locate schema given a name space URI (e.g. XML catalog facility available in WSAD); in such case the asiSchemaLocation attribute does not have to be present.

• ASI annotations on the business object schema which is of interest to the Editor. The Editor has all the pertinent information (schema definition of describing the shape/structure of the annotation through ASI) to provide a rich editing experience.

In the example in the Appendix, two ASI schemas are identified in the PurchaseOrder schema to the editor

• eis1Schema.xsd having asiNSURI=http://www.eis1.com/asi, and

• eis2Schema.xsd. having asiNSURI="http://www.eis2.com/asi".

<?xml version="1.0" encoding="UTF-8"?> <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:po="http://www.mycompany.com" targetNamespace="http://www.mycompany.com"> <annotation> <documentation xml:lang="en"> Purchase order schema for Example.com. Copyright 2000 Example.com. All rights reserved. </documentation> <appinfo source="commonj.emd.asi"> <emd:annotationSet xmlns:emd="commonj.emd.asi" asiNSURI="http://www.eis1.com/asi" asiSchemaLocation="eis1Schema.xsd"/> </appinfo> </annotation>

The instances of global element declarations defined in EIS schema can appear as annotations on the business object schema element, complex type, attribute declarations. An ASI appinfo must contain the XML instance of one global element declaration defined in the EIS schema. These instances are validated against the global element declaration defined in ASI schema using the standard XML schema validation facilities. Also additional validation checks are done to ensure that only those declarations of global elements which were annotated with framework schema appear on the respective declarations in the business object schema. For example BusinessObjectASI element declaration in the EIS schema defined in the Appendix was marked to appear on global complex types only; it would be a validation error if it had appeared on a local complex type or an element declaration. As mentioned before, all annotations within the appinfo tag are disambiguated with the source attribute tag set to namespace URI of the annotating schema; in this case it would be namespace URI of the EIS


Page 80 of 114

schema. For example, the annotation below pertains to the EIS schema having namespace URI “http://www.eis1.com/asi” .

<element name="purchaseOrder" type="po:PurchaseOrderType"/> <element name="comment" type="string"/> <complexType name="PurchaseOrderType"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:BusinessObjectASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:ObjectName>eis1.PurchaseOrder1</ns1:ObjectName> </ns1:BusinessObjectASI> </appinfo> </annotation> <sequence>

9.5. Tool requirements A tool must

• The tool is responsible for invoking the DataBindingGenerator.generateDataBinding() method, when the DataDescription provides a DataBindingGenerator class name.

• Provide support for type editing if ASI schema are provided. A tool may

• Provide validation of ASI within a business object schema.

9.6. Discovery service requirements The discovery service provider must

• Provide a generic data binding or a data binding generator. • Generate a DataBinding or CCI Record from the data binding generator. • Within the appinfo, define the namespace used for ASI.

The discovery service provider may

• Provide ASI schema for type editing support.


Page 81 of 114

10. Installing/Bootstrapping/Packaging

All the discovery service classes and configuration files are packaged along with the resource adapter archive (.rar file). In addition to the usual components of a resource adapter archive, this specification has additional requirements to enable the resource adapter for discovery.

Apart from the resource adapters deployment descriptor ( ra.xml ), there must also be a tooling deployment descriptor ( discovery-service.xml ) in the META-INF directory. The schema for this configuration file is located in the appendix and it is also packaged along with the jar file for this specification. This configuration file defines all the parameters for the tool to initiate the discovery service. Detailed element documentation is provided in the schema. The key elements of this schema are:

• metadataDiscovery-class

This is a required element and it indicates the fully qualified implementation class of the DiscoveryService interface. This class is instantiated when the resource adapter is loaded by the tool. This class is instantiated using the default constructor. Once this class is instantiated, the tool can initiate the discovery process. If there are any properties that need to be set on the newly instantiated instance of this class, they could be loaded from a configuration file that is packaged along with the resource adapter. Upon the instantiation of the class, the class could read these properties and set them on itself. This is just a suggestion, and EMD makes no requirements about how the DiscoveryService instance is initialized internally.

• metadataEdit-class

This is also a required element and it indicates the fully qualified class that implements the MetadataEdit interface. All resource adapters must support this functionality. The tool should support this functionality. This class is instantiated using the default constructor.

• application-specific-schema

This element is used to indicate all the application specific schemas that are needed to generate the service after discovery. This is an optional element and there can be more than one. For each of the application specific schema’s the configuration should indicate its namespace and schema location. If this schema is local to the resource adapter, it will be loaded by the classloader of the resource adapter. The tooling must support this functionality. Each definition of an application specific schema has:

i. asiNSURI

Identifies the namespace of the ASI Schema.

ii. asiSchemaLocation

The location of the schema file. If local to the resource adapter then the schema is found using the classloader for the resource adapter archive. In this case the name would need to be a valid resource path name.


Page 82 of 114

10.1. Tool requirements • The tool should support the metadata edit functionality (Note: MetadataDiscovery support and

MetadataEdit support might be delivered in different tools).

• The tool must support the discovery functionality.

• The tool must support application specific schemas.

An administrative tool would not take advantage of the discovery functionality. It may choose to take advantage of the metadata edit functionality.

10.2. Discovery service requirements • The resource adapter vendor (or user) is required to specify a valid discovery-service.xml in the

META-INF directory of the resource adapter archive if the resource adapter is to be used by a tool that supports discovery.

• All classes that the required for discovery and metadata edit must be packaged in the resource adapter archive.

• The resource adapter must support metadata edit.

• The resource adapter should support discovery.


Page 83 of 114

11. Runtime This section of the document presents the runtime scenarios of invoking the services imported using the discovery service. The goal is to show how runtime interfaces are used during service invocations and how the ServiceDescription can be mapped to the runtime using these interfaces.

11.1. Service generation The specification does not prescribe specific format for the generated service interface. The format depends on the environment in which the service interface will be executing. This section assumes the target environment is a J2EE environment; however it is only for illustration purposes, the actual implementation may be different.

11.2. Outbound Service The outbound service runtime uses the data binding interfaces presented in section 9 . It does not introduce any additional constructs or interfaces and relies entirely on the common client interfaces defined by the Connector Architecture specification. A sample generated outbound service invocation is presented on the following figure, the following text contains a description of how the code is generated.


public class AccountService { 1 2 public AccountDataObject getAccount(CustomerDataObject customer){ 3 4 ConnectionFactory connectionFactory = getConnectionFactory(); 5 6 // Create and configure InteractionSpec 7 ERPInteractionSpec interactionSpec = new ERPInteractionSpec(); 8 interactionSpec.setProperty1(…); 9 interactionSpec.setProperty2(…); 10 11 // Create instance of the Interaction 12 Connection connection = connectionFactory.getConnection(); 13 Interaction interaction = connection.createInteraction(); 14 15 // Instantiate data bindings 16 RecordDataBinding inputBinding = new CustomerBindingImpl(); 17 RecordDataBinding outputBinding = new AccountBindingImpl(); 18 19 // Set service argument on the input data binding 20 inputBinding.setDataObject(customer); 21 22 if(supportsInputOutputExecute) 23 interaction.execute(interactionSpec, inputBinding,outputBinding); 24 25 return (AccountDataObject)outputBinding.getDataObject(); 26 27 } 28 29 … 30 31 public ConnectionFactory getConnectionFactory(){ 32 33 // Create ConnectionFactory in the non-managed environment 34 ManagedConnectionFactory mcf = new ERPManagedConnectionFactory(); 35 mcf.setProperty1(…); 36 mcf.setProperty2(…); 37 38 ConnectionFactory cf = mcf.createConnectionFactory(); 39 40 // OR lookup ConnectionFactory managed 41 // ConnectionFactory cf = context.lookup(“eis/ERPConnectionFactory”); 42 43 } 44 }45

Page 84 of 114


The AccountService Java proxy had been generated from the ServiceDescription which contains sufficient information to the service specific contents of the invocation proxy bean as follows. The outbound service description contains the OutboundConfiguration properties. These properties are mapped to the properties of the Managed Connection Factory using the ConnectionType and its synchronization to the outbound connection beans functionality. The connection, defined using these properties, is applicable to all functions defined for the outbound service. In the sample, it is generated into the separate method, getConnectionFactory() to be available for all the service function invocations (lines 35 – 37). The service invocation could be invoked in non-managed mode, or in the managed J2EE environment, the connection factory with those properties could be deployed to the server and then looked up in JNDI context instead of being created by the factory instance (lines 41 -- 42). Depending on the adapter, the instance of the ResourceAdapter Java Bean can also be deployed. The deployment would use the same mechanism, ConnectionType synchronization, to configure bean properties from the OutboundConfiguration.

• Each OutboundFunctionDescription, contained in the ServiceDescription, represents a full description of the service function and is mapped into a Java method (lines 3 – 28). The function description includes the instance of the InteractionSpec, populated with the values needed to access a specific function of the service. The state of the InteractionSpec is saved into the Java method (lines 8 – 10).

• The input and output data descriptions are used to create the service arguments, service data objects. Also data bindings that would map the data objects to the adapter understandable data format are created. These objects are created by the tooling environment from the schema definitions of the DataDescription. The data bindings are specific for each data object thus being generated by the data binding generator also provided by the DataDescription. The data bindings are also saved into the method (lines 17 –18).

The getAccount method uses CCI interfaces to connect to the EIS and execute interactions with it. The execution flow of the method is dictated by CCI and defined by the J2EE Connector Architecture specification. The method starts with establishing the connection with the target EIS using a ManagedConnectionFactory instance. This instance is used to create a ConnectionFactory, which in turn is used to create a Connection. Using the connection, the Interaction object is created. Next, the suitable instance of the InteractionSpec is created and configured with properties. In the next step, the service invocation arguments are prepared. The input and output data bindings are created, the method argument is set on the input data binding and the execute method is invoked passing both data bindings. In this case, the resource adapter supports the execute method with input and output and the data bindings are required to implement the RecordDataBinding interface. When the method returns, the result is extracted from the output data binding and returned to the method caller. In the sample, the resource adapter, used to access the service implementation, supports the execute method with input only, the data binding implementation is required to support

Page 85 of 114


RecordHolderDataBinding interface. In that case, the interaction with the adapter requires using data binding to create or consume CCI Records as shown in the figure below.

… RecordHolderDataBinding inputBinding = new CustomerHolderBindingImpl(); RecordHolderDataBinding outputBinding = new AccountHolderBindingImpl(); inputBinding.setDataObject(customer); Record result = interaction.execute(interactionSpec, inputBinding.getRecord()); outputBinding.setRecord(result); return (AccountDataObject)outputBinding.getDataObject(); …

The sample runtime, so far, presented data bindings specific to the type of service arguments or return value. Those data bindings would have been generated using DataBindingGenerator provided by the data description. If the data description returns the generic data binding implementation class name, the arguments and returned values of all the service functions will use the same data binding. The generic data binding must as well implement the correct interface, either RecordDataBinding or RecordHolderDataBinding, depending on the type of execute method supported by the resource adapter. The following figure shows the sample code with the generic data binding implementation.

… RecordHolderDataBinding inputBinding = new DataBindingImpl(); RecordHolderDataBinding outputBinding = new DataBindingImpl (); inputBinding.setDataObject(customer); Record result = interaction.execute(interactionSpec, inputBinding.getRecord()); outputBinding.setRecord(result); return (AccountDataObject)outputBinding.getDataObject(); …

The specification also allows the data binding generator to generate the CCI Records instead of data binding instances. If records are generated, the code to invoke the service can use them directly. The fragment of an example invocation is shown on the figure below.

public Account getAccount(Customer customer){ ConnectionFactory connectionFactory = getConnectionFactory(); ERPInteractionSpec interactionSpec = new ERPInteractionSpec(); … Connection connection = connectionFactory.getConnection(); Interaction interaction = connection.createInteraction(); Record result = interaction.execute(interactionSpec, (Record)customer);

Page 86 of 114


return (Account)result; }

11.3. Inbound Service The inbound service runtime introduces two interfaces in addition to the data binding interfaces described in the data binding section, the FunctionSelector and the InboundListener. The FunctionSelector interface is presented in the following figure.

Figure 11.1: The FunctionSelector interface

The FunctionSelector’s role is to generate the name of the EIS function or a key identifying the inbound service invocation from the adapter specific message listener arguments. The EIS function name must correspond to the EIS function name of one of the inbound function descriptions, as returned by its getEISFunctionName method. The EIS function name is used by the runtime to determine which method of the target object to invoke. The InboundListener interface, presented below, allows the execution of the inbound service that provides notification without expecting a reply.

Figure 11.2: The InboundListener interface

Page 87 of 114


The InboundListener interface extends the MessageListener interface defined by CCI and allows the adapter to provide one-way notification as well two-way inbound communication (request and response).

11.3.1. Standard Message Listeners It is recommended that the resource adapter or the service provider supports the InboundListener and/or MessageListener interfaces. This simplifies the generated implementation of the services and interaction with the tools. The sample code generated for inbound service invocation is presented below, followed by the description of how the code is generated.

Page 88 of 114


public class CustomerSourceMDBBean implements MessageListener, MessageDrivenBean { public void ejbCreate(){ initialize(); } private void initialize(){ methodNamesTable = new HashMap(); inputDataBindingTable = new HashMap(); outputDataBindingTable = new HashMap(); methodNamesTable.put(EISFunctionName_1, FunctionName_1); … methodNamesTable.put(EISFunctionName_n, FunctionName_n); inputDataBindingTable.put(EISFunctionName_1, new AccountBindingImpl()) … inputDataBindingTable.put(EISFunctionName_n, new …BindingImpl()) outputDataBindingTable.put(EISFunctionName_1, new CustomerBindingImpl()) … outputDataBindingTable.put(EISFunctionName_n, new …BindingImpl()) } public Record onMessage(Record inputRecord) throws ResourceException { FunctionSelector functionSelector = new ERPSelectorImpl(); String EISfunctionName = functionSelector.generateEISFunctionName( new Object[] {inputRecord}); String methodName = methodNamesTable.get(EISfunctionName); RecordHolderDataBinding inputBinding = inputDataBindingTable.get(EISfunctionName); RecordHolderDataBinding outputBinding = outputDataBindingTable.get(EISfunctionName); inputBinding.setRecord(inputRecord); DataObject inputDataObject = inputBinding.getDataObject(); Method m = targetClass.getMethod(methodName, new Class[] {inputDataObject.getClass()}); DataObject result = (DataObject)m.invoke(target, new Object[]{inputDataObject}); outputBinding.setDataObject(result); Record resultRecord = outboundBinding.getRecord(); return resultRecord; }

The service description contains all the information necessary to generate the service invocation presented above. The difference between the inbound and outbound scenarios, however, is that the

Page 89 of 114


inbound service can only be run in the managed mode and requires the J2EE application server. The J2EE Connector Architecture specification does not support a non-managed execution of the inbound communication. The service description is used to generate the inbound service invocation as follows.

• The inbound service description contains information to deploy a message driven bean in the application server. The InboundServiceConfiguration contains properties of the ResourceAdapter and ActivationSpec Java Beans. These properties are used to configure and deploy a MDB to the J2EE server.

• The listener interface from the inbound service description determines the interface implemented by the MDB, in the sample, the MessageListener (line 1).

• The function selector class name, also provided by the description is used to generate code to instantiate the selector used by the MDB (line 31).

• The array of inbound function descriptions is used in two different ways. First, to create a table capturing the relationship between the EIS function name and the service function name. The former is provided by the getEISFunctionName method of the description. The generated code initializes the methodNamesTable map with this relationship (lines 13 – 15). The second role of the function description table is to create a set of methods, for example grouped as a service interface, implementation of which may be invoked by the MDB in response to the inbound request. The method name is retrieved form the methodNamesTable (line 36) and then created and invoked (lines 48 – 51).

• The input and output data descriptions are used for generation in the same manner as for the outbound service. They are used to create the inbound service arguments, service data objects and data bindings that would map the message listener arguments to the service arguments’ data objects. Since all the inbound service requests are invoked through one listener interface method, the data bindings, which can be specific to the particular function arguments, need to be associated with the function corresponding to the function description defining bindings. This is achieved using inbound and outbound data binding tables where the input and output data binding is associated with the EIS function name (lines 17 – 23), the EIS function name is the key and the value is the instance of the data binding class, either generic or generated.

The onMessage method of the Message Driven Bean (MDB) is invoked by the resource adapter using standard inbound event mechanism defined in the J2EE Connector Architecture specification. Inside the method, the FunctionSelector is created (line 31) and the method argument is used by it to get the EIS function name (line 33 – 34). It determines the name of the method of the service to invoke (line 36). The EIS function name is also a key to table with the input and output data bindings (line 37 – 41). The method is invoked with the data objects created by the DataBinding (lines 44 -- 46), result of the interaction is set on the data binding (line 53) and the record retrieved from it (line 55) is returned to the resource adapter.

The allowed data bindings are analogous to the outbound service generation, they can be type specific, created by the data binding generator, as shown in the previous sample, but also generic data binding can be used, as shown in the sample below.

Page 90 of 114


public Record onMessage(Record inputRecord) throws ResourceException { FunctionSelector functionSelector = new ERPSelectorImpl(); String EISfunctionName = functionSelector.generateEISFunctionName( new Object[] {inputRecord}); String methodName = methodNamesTable.get(EISfunctionName); // Use generic data bindings, since they are the same for any service // method, there is no need to associate these bindings with a // specific method RecordHolderDataBinding inputBinding = new DataBindingImpl(); RecordHolderDataBinding outputBinding = new DataBindingImpl (); inputBinding.setRecord(inputRecord); DataObject inputDataObject = inputBinding.getDataObject(); DataObject result = (DataObject)m.invoke(target, new Object[]{inputDataObject}); outputBinding.setDataObject(result); Record resultRecord = outboundBinding.getRecord(); return resultRecord; }

Since the generic data bindings are applicable to all service functions, there is no need to group them based on the function they belong to, the same data bindings are used for all the service invocations. The DataBindingGenerator can also create a CCI Record instead of the data binding. In that case, the inbound service for the specific function, for which there was no data binding generated, must be able to accept the CCI Record arguments. The generated runtime could be as follows.

public class CustomerSourceMDBBean implements InboundListener, MessageDrivenBean { public Record onMessage(Record inputRecord) throws ResourceException { FunctionSelector functionSelector = new ERPSelectorImpl(); String EISfunctionName = functionSelector.generateEISFunctionName( new Object[] {inputRecord}); String methodName = methodNamesTable.get(EISfunctionName); RecordHolderDataBinding inputBinding = inputDataBindingTable.get(EISfunctionName); RecordHolderDataBinding outputBinding = outputDataBindingTable.get(EISfunctionName); if(inputBinding == null){ Method m = targetClass.getMethod(methodName,

Page 91 of 114


new Class[] { inputRecord.getClass()}); Object result = m.invoke(target, new Object[]{inputRecord}); if(outputBinding == null){ return (Record)result; } … } … }

If there is no data binding for the specific function, the runtime assumes the CCI Record is the type of the service and invokes it. Unlike the outbound case, where the execute method is typed with the Record, the service methods can take any type of arguments and it this case it may be difficult for the runtime to ensure type safety of the service invocation.

11.3.2. Adapter Specific Message Listener The discussion so far had assumed that resource adapter supports one of the EMD recommended interfaces, the MessageListener or InboundListener. This is not, however, a requirement. To support resource adapters using other listener interfaces, the specification provides the InboundNativeDataRecord interface. The Adapter may support the following interface

public interface EISListener{ public Object inboundEvent(Object arg1, Integer arg2); … }

The sample runtime generated code could look as follows.

public class CustomerSourceMDBBean implements EISListener, MessageDrivenBean { public Object inboundEvent(Object arg1, Integer arg2); FunctionSelector functionSelector = new ERPSelectorImpl(); String EISfunctionName = functionSelector.generateEISFunctionName( new Object[] {arg1, arg2}); String methodName = methodNamesTable.get(EISfunctionName); RecordHolderDataBinding inputBinding = inputDataBindingTable.get(EISfunctionName); RecordHolderDataBinding outputBinding =

Page 92 of 114


outputDataBindingTable.get(EISfunctionName); InboundNativeDataRecord input = InboundNativeDataRecordImpl(); input.setNativeData(new Object[] {arg1, arg2}); inputBinding.setRecord(input); DataObject inputDataObject = inputBinding.getDataObject(); Method m = targetClass.getMethod(methodName, new Class[] {inputDataObject.getClass()}); DataObject result = (DataObject)m.invoke(target, new Object[]{inputDataObject}); outputBinding.setDataObject(result); InboundNativeDataRecord resultRecord = (InboundNativeDataRecord)outboundBinding.getRecord(); return resultRecord.getNativeData[0]; } }

The runtime creates the input and output data bindings and then uses the InboundNativeDataRecord to present the listener interface arguments, an Object and an Integer, as a CCI Record to the data binding. The data binding implementation must understand the InboundNativeDataRecord and accesses the array of listener arguments for processing. The contract between the runtime and resource adapter and binding implementation provider is that if the adapter implements custom listener interface e.g. EISListener, the data binding supplied to the runtime, generic or generated, must be able to interpret its record contents as InboundNativeDataRecord. The record is only argument list holding its contents depends on the direction of execution it is used. For passing arguments to input bindings, the native data is a set of arguments matching exactly types and order of the listener interface. In the sample, it would contain arg1, an Object at index 0 and arg2, an Interger at index 1. When the output data binding would use it to return result of the operation, it would set the element 0 of the native data array to the result, subsequently retrieved and returned to the resource adapter.

11.4. Runtime Exceptions The runtime defines two exceptions presented below.

Page 93 of 114


Figure 11.3: Runtime Exceptions

Both exceptions defined by the runtime are checked exceptions that extend the Exception class. This allows them to propagate the cause of the problem, usually another original exception, into the runtime. The SelectorException is used to report any problem related to the derivation of the EIS function name from the listener arguments. The DataBindingException reports any problem related to the execution of the implementation of the data bindings.

11.5. Tool requirements If the Tool generates runtime code, it must invoke data bindings and, for inbound services, the function selector provided by the Resource Adapter

11.6. Discovery service requirements Resource Adapter must

• Provide or support RecordDataBinding if the adapter supports execute method with input and output

• Provide or support RecordHolderDataBinding if the adapter supports execute method with input only

• Support RecordHolderDataBinding if adapter supports inbound services and MessageListener or InboundListener interfaces.

• Support or provide InboundNativeDataRecord if adapter supports inbound services and custom listener interface

• Provide FunctionSelector implementation if adapter supports inbound services

Page 94 of 114


12. Edit This chapter specifies the contract between a tool and the discovery service in terms of editing and administration support.

12.1. Service description editing Service description editing can be performed in two modes:

• disconnected, where there the discovery process is not used • connected, where the discovery process is used

12.1.1. Editing in disconnect mode Disconnect editing is useful for quick editing of connection or interaction beans, and administered objects. Each discovery service must implement the MetadataEdit interface. The tool uses this interface to perform disconnect editing. Once the tool has an instance of a MetadataEdit implementation as specified through the discovery-service.xml, it can use it to edit

• InteractionSpec, • ConnectionSpec, • Administered objects, • ResourceAdapter JavaBean, • ActivationSpec JavaBean, and • ManagedConnectionFactory JavaBean.

For resource adapters which do not have a discovery service, the MetadataEdit implementation will provide rich editing support. The interfaces involved in disconnect editing are shown in the metadata edit interfaces figure below.

Page 95 of 114


Figure 12.1: Metadata edit interfaces The flow of interaction using EditableType is shown below. The user will select an InteractionSpec, ConnectionSpec or administered object for editing. For example, the tool would invoke the getInteractionSpecType method passing the class name of the InteractionSpec. The tool would then create a default instance of the PropertyGroup for the InteractionSpec by invoking the createProperties method on the EditableType. The tool would synchronize the values of the InteractionSpec to the PropertyGroup by invoking the synchronizeFromBeanToPropertyGroup method on EditableType. The tool would then render the PropertyGroup allowing the user to edit it. Once editing is finished, the tool would synchronize the updated values of the PropertyGroup to the InteractionSpec by invoking the synchronizeFromPropertyGroupToBean method on EditableType. The tool can then save the change to the service interface.

Page 96 of 114


Figure 12.2: Metadata edit with EditableType The flow of interaction using OutboundConnectionType when editing ResourceAdapter Java bean or ManagedConnectionFactory is shown below. The flow of interaction using the InboundConnectionType when editing ResourceAdapter Java bean or ActivationSpec is similar. For example, the user will select to edit the ManagedConnectionFactory of a service interface. The tool would invoke the getOutboundConnectionType method passing the class name of the ManagedConnectionFactory. The tool would then create the corresponding OutboundConnectionType from which it creates the OutboundConnectionConnectionConfiguration. The tool would then invoke the createManagedConnectionFactoryProperties on the OutboundConnectionConfiguration, and then synchronize the values of the ManagedConnectionFactory to the PropertyGroup by invoking the synchronizeFromManagedConnectionFactoryToPropertyGroup method on OutboundConnectionType. The tool would then render the PropertyGroup allowing the user to edit it. Once editing is finished the tool would synchronize the updated values of the PropertyGroup to the ManagedConnectionFactory by invoking the synchronizeFromPropertyGroupToManagedConnectionFactory method on OutboundConnectionType. The tool can then save the change to the service interface.

Page 97 of 114


Figure 12.3: Metadata edit with ConnectionType

12.1.2. Editing in connect mode Editing in the context of the MetadataConnection requires the tool to save metadata information with the service interface so that it can revive the state of the connection at the time import occurred. Some resource adapter implementations may require this capability to provide meaningful edits of interaction or connection properties. This will also allow the user to make incremental updates to the service interface, by adding or removing business objects or functions to the service interface. To re-establish the MetadataConnection, the following information must be saved:

• MetadataDiscovery implementation, • AdapterType ID to get the correct AdapterType, • ConnectionType ID to get the correct OutboundConnectionType, and • OutboundConnectionConfiguration metadata connection.

The diagram below describes how to re-establish the MetadataConnection.

Page 98 of 114


Figure 12.4: Service edit: re-establishing the MetadataConnection The tool creates the MetadataTree using the MetadataDiscovery.getMetadataTree() method passing the MetadataConnection. The tool then creates the MetadataSelection using the MetadataTree.createSelection() method. To re-establish the selected objects for import, the following information must be saved:

• Location ID for each function. This will allow each selected MetadataObject to be retrieved. • MetadataImportConfiguration properties to configure the MetadataObject.

The tool can optimize saving the information for a MetadataObject which may be applied to more than one function. This can be determined by checking the location ID for each function. Once the MetadataObject is configured it is added to the MetadataSelection.

Page 99 of 114


Figure 12.5: Service edit: adding MetadataObjects to MetadataSelection The tool should now allow the user to add to, update, or remove the MetadataObjects it has in the MetadataSelection. Update can be supported by combining a remove and add of the MetadataObject. To re-establish the MetadataSelection for import, the following information must be saved:

• MetadataSelection properties. To re-establish the connection properties of the service description, the following information must be saved:

• ConnectionConfiguration properties of the service description.

12.1.3. Type Editing A service’s types are described using XSD. Editing of these types can be accomplished by the service editing described in section 12.1.2 and the type editing support described in section 9.4 .

Page 100 of 114


12.2. Administration Resource adapters need to be configured on the application server. Application server administration consoles can choose to use disconnect editing support described above to provide rich editing of administered objects, ResourceAdapter, ManagedConnectionFactory, and ActivationSpec JavaBeans.

12.3. Tool requirements The tool must provide

• Service editing support Administration consoles may choose to use the stand alone service editing support.

12.4. Discovery service requirements The discovery service must provide

• MetadataEdit implementation • EditableType implementations for each of its ConnectionSpec, InteractionSpec, and

administered objects • ConnectionType implementations for each of its runtime inbound or outbound connections.

The tool will obtain a ConnectionConfiguration from the ConnectionType, and from the ConnectionConfiguration the PropertyGroups for editing connections.

Page 101 of 114


13. Acknowledgements From BEA, we would like to thank John Beatty, Kathryn Begley, Brian Chesebro, Ed Cobb, Jim Gish, Yaron Goland, Stephen Hess, and Michael Rowley. From IBM, we would like to thank Michael Beisiegel, Jean-Sebastien Delfino, Suman Kalia, Vlad Klicnik, Amy Mollin, and Suraksha Vidyarthi.

Page 102 of 114


14. Appendix A: Discovery Service Bootstrap schema

14.1. discovery-service.xsd <?xml version = "1.0" encoding = "UTF-8"?> <xsd:schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="commonj.connector" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:emd="commonj.connector" xmlns:j2ee="http://java.sun.com/xml/ns/j2ee" elementFormDefault="qualified" attributeFormDefault="unqualified" version="1.0"> <xsd:annotation> <xsd:documentation> discovery-service.xsd 1.0 01/31/05 </xsd:documentation> </xsd:annotation> <xsd:annotation> <xsd:documentation> Copyright BEA Systems, Inc. and International Business Machines Corp 2005. All rights reserved. IBM and BEA (collectively, the Authors) agree to grant you a royalty-free license, under reasonable, non-discriminatory terms and conditions to patents that they deem necessary to implement the Enterprise Metadata Discovery Specification. </xsd:documentation> </xsd:annotation> <xsd:annotation> <xsd:documentation> This is the XML Schema for the Enterprise Metadata Discovery service. The deployment descriptor must be named "META-INF/discovery-service.xml" in the connector's rar file. The discovery-service.xml is used to bootstrap the resource adapter to the discovery service tool. </xsd:documentation> </xsd:annotation> <xsd:import namespace="http://java.sun.com/xml/ns/j2ee" schemaLocation="http://java.sun.com/xml/ns/j2ee/j2ee_1_4.xsd"/> <xsd:element name="discoveryService" type="emd:discoveryServiceType"> <xsd:annotation> <xsd:documentation> The discoveryService element is the root element of the discovery servicee for the resource adapter. This element includes general information - discovery service vendor name, version, icon - about the discovery service. It also includes information specific to the implementation of the discovery service. </xsd:documentation> </xsd:annotation> </xsd:element> <xsd:complexType name="discoveryServiceType"> <xsd:sequence> <xsd:group ref="j2ee:descriptionGroup"/> 

Page 103 of 114


<xsd:element name="vendor-name" type="j2ee:xsdStringType"> <xsd:annotation> <xsd:documentation> The element vendor-name specifies the name of discovery service provider vendor. </xsd:documentation> </xsd:annotation> </xsd:element>  <xsd:element name="version" type="j2ee:xsdStringType"> <xsd:annotation> <xsd:documentation> The element version specifies a string-based version of the discovery service. </xsd:documentation> </xsd:annotation> </xsd:element>  <xsd:element name="spec-version" type="j2ee:dewey-versionType" > <xsd:annotation> <xsd:documentation> EMD specification version. </xsd:documentation> </xsd:annotation> </xsd:element>  <xsd:element name="discoveryService-class" type="j2ee:fully-qualified-classType"> <xsd:annotation> <xsd:documentation> The fully qualified class that implements the MetadataDiscovery interface. </xsd:documentation> </xsd:annotation> </xsd:element>  <xsd:element name="metadataEdit-class" type="j2ee:fully-qualified-classType"> <xsd:annotation> <xsd:documentation> The fully qualified class that implements the MetadataEdit interface. </xsd:documentation> </xsd:annotation> </xsd:element>  <xsd:element name="application-specific-schema" type="emd:application-specific-schema" minOccurs="0" maxOccurs="unbounded"> <xsd:annotation> <xsd:documentation> Lists the application specific schemas. </xsd:documentation> </xsd:annotation> </xsd:element>  </xsd:sequence> </xsd:complexType> <xsd:complexType name="application-specific-schema"> <xsd:annotation>

Page 104 of 114


<xsd:documentation> Identifies information on an application specific schema including a display name, description and location of the schema. </xsd:documentation> </xsd:annotation> <xsd:sequence> <xsd:group ref="j2ee:descriptionGroup"/>  <xsd:element name="asiNSURI" type="xsd:anyURI"> <xsd:annotation> <xsd:documentation> Identifies the namespace of the ASI Schema. </xsd:documentation> </xsd:annotation> </xsd:element>  <xsd:element name="asiSchemaLocation" type="xsd:anyURI" > <xsd:annotation> <xsd:documentation> The location of the schema file. If local to the resource adapter then the schema is found using the classLoader for the resource adapter archive. In this case the name would need to be a valid resource path name. </xsd:documentation> </xsd:annotation> </xsd:element>  </xsd:sequence> </xsd:complexType> </xsd:schema>

Page 105 of 114


15. Appendix B: Type support

15.1. ASI Schema <?xml version="1.0" encoding="UTF-8"?> <xsd:schema xmlns="http://www.w3.org/2001/XMLSchema" targetNamespace="commonj.connector.asi" xmlns:asi="commonj.connector.asi" xmlns:xsd="http://www.w3.org/2001/XMLSchema" elementFormDefault="qualified" version="1.0"> <xsd:annotation> <xsd:documentation> asiSchema.xsd 1.0 01/31/05 </xsd:documentation> </xsd:annotation> <xsd:annotation> <xsd:documentation> Copyright BEA Systems, Inc. and International Business Machines Corp 2005. All rights reserved. IBM and BEA (collectively, the Authors) agree to grant you a royalty-free license, under reasonable, non-discriminatory terms and conditions to patents that they deem necessary to implement the Enterprise Metadata Discovery Specification. </xsd:documentation> </xsd:annotation> <xsd:annotation> <xsd:documentation> For schema which is used to describe business objects that can be accessed from an enterprise information system, you need to be able to specify application specific information (ASI). ASI is used by an application to map the business object into its corresponding enterprise entity. Providing schema that describes the ASI that can occur on a complexType, element, or attribute will enable rich editing support and validation. There are two notions of anchor points here. The first being able to anchor - ASI schema to complexTypes, - ASI schema to elements, and - ASI schema to attributes. The second being able to anchor the above set of schema to a business object schema. A set of schema that applies to a business object may have more than one ASI schema for complexTypes, elements, or attributes. For example, there may be two ASI declarations for what can be stored on elements. An enterprise information system may have more than one set of ASI schema. For example, the ASI may differ between SAP RFC and SAP BAPI. A business object schema may apply to more than one enterprise information system. Schema provides the appinfo annotation as a location for storing information for tooling and applications. </xsd:documentation> </xsd:annotation> <xsd:element name="annotationSet">

Page 106 of 114


<xsd:annotation> <xsd:documentation> ASI anchor which is used on the business object schema element declaration. The asiNSURI must be specified; it identifies the namespace of the ASI schema. The asiSchemaLocation is an optional hint that can be used to identify the location of the ASI schema. Example: <schema ...> <annotation> <appinfo source="commonj.connector.asi"> <asi:annotationSet xmlns:asi="commonj.connector.asi" asiNSURI="http://www.eis.com/asi" asiSchemaLocation="http://www.eis.com/asi/eisSchema.xsd"/> </appinfo> </annotation> ... </schema> </xsd:documentation> </xsd:annotation> <xsd:complexType> <xsd:complexContent> <xsd:restriction base="anyType"> <xsd:attribute name="asiNSURI" type="anyURI"/> <xsd:attribute name="asiSchemaLocation" type="anyURI" use="optional"/> </xsd:restriction> </xsd:complexContent> </xsd:complexType> </xsd:element> <xsd:simpleType name="annotationKind"> <xsd:annotation> <xsd:documentation> Specifies the kind of the annotation anchor, which can be complexType, element or attribute. </xsd:documentation> </xsd:annotation> <xsd:restriction base="string"> <xsd:enumeration value="complexType"/> <xsd:enumeration value="element"/> <xsd:enumeration value="attribute"/> </xsd:restriction> </xsd:simpleType> <xsd:simpleType name="annotationScope"> <xsd:annotation> <xsd:documentation> Specifies the scope of the annotationKind ie whether it is applicable to local or global constructs of schema (eg. local elements or global elements). </xsd:documentation> </xsd:annotation> <xsd:restriction base="string"> <xsd:enumeration value="local"/> <xsd:enumeration value="global"/> <xsd:enumeration value="both"/> </xsd:restriction> </xsd:simpleType> <xsd:element name="annotationType"> <xsd:annotation> <xsd:documentation> Identifies the anchor point for complexType, element or attribute ASI schema. Located as appinfo on global elements in the provider ASI schema. The global element's type describes the ASI. The appinfo on the global element identifies where the ASI

Page 107 of 114


can be used. The annotationKind must be specified and associates the ASI being described to the XSD component it can be used with. The annotationScope is optional. If it is not used then the ASI can be used on global and local declarations. If it is specified the ASI is scoped to either being used on global or local declarations. Example: <element name="BusinessObjectASI" type="eis1:BusinessObjectASIType"> <annotation> <appinfo source="commonj.connector.asi"> <asi:annotationType xmlns:asi="commonj.connector.asi" annotationKind="complexType" annotationScope="global" /> </appinfo> </annotation> </element> <complexType name="BusinessObjectASIType"> <sequence> <element name="ObjectName" type="string" /> </sequence> </complexType> <element name="ElementASI" type="eis1:ElementASIType"> <annotation> <appinfo source="commonj.connector.asi"> <asi:annotationType xmlns:asi="commonj.connector.asi" annotationKind="element" annotationScope="local" /> </appinfo> </annotation> </element> <complexType name="ElementASIType"> <sequence> <element name="getMethodName" type="string" /> <element name="setMethodName" type="string" /> </sequence> </complexType> </xsd:documentation> </xsd:annotation> <xsd:complexType> <xsd:complexContent> <xsd:restriction base="anyType"> <xsd:attribute name="annotationKind" type="asi:annotationKind"/> <xsd:attribute name="annotationScope" type="asi:annotationScope" default="both" use="optional"/> </xsd:restriction> </xsd:complexContent> </xsd:complexType> </xsd:element> </xsd:schema>

15.2. Sample EIS Schema EIS Schema 1: <?xml version="1.0" encoding="UTF-8"?> <schema targetNamespace="http://www.eis1.com/asi" xmlns:eis1="http://www.eis1.com/asi"

Page 108 of 114


xmlns="http://www.w3.org/2001/XMLSchema"> <element name="BusinessObjectASI" type="eis1:BusinessObjectASIType"> <annotation> <appinfo source="commonj.emd.asi"> <emd:annotationType xmlns:emd="commonj.emd.asi" annotationKind="complexType" annotationScope="global" /> </appinfo> </annotation> </element> <complexType name="BusinessObjectASIType"> <sequence> <element name="ObjectName" type="string" /> </sequence> </complexType> <element name="ElementASI" type="eis1:ElementASIType"> <annotation> <appinfo source="commonj.emd.asi"> <emd:annotationType xmlns:emd="commonj.emd.asi" annotationKind="element" annotationScope="local" /> </appinfo> </annotation> </element> <complexType name="ElementASIType"> <sequence> <element name="getMethodName" type="string" /> <element name="setMethodName" type="string" /> </sequence> </complexType> </schema>

EIS Schema 2 <?xml version="1.0" encoding="UTF-8"?> <schema targetNamespace="http://www.eis2.com/asi" xmlns:eis2="http://www.eis2.com/asi" xmlns="http://www.w3.org/2001/XMLSchema"> <element name="BusinessObjectASI" type="eis2:BusinessObjectASIType"> <annotation> <appinfo source="commonj.emd.asi"> <emd:annotationType xmlns:emd="commonj.emd.asi" annotationKind="complexType"/> </appinfo> </annotation> </element> <complexType name="BusinessObjectASIType"> <sequence> <element name="ObjectName" type="string" /> </sequence> </complexType> <element name="ElementASI" type="eis2:ElementASIType"> <annotation> <appinfo source="commonj.emd.asi"> <emd:annotationType xmlns:emd="commonj.emd.asi" annotationKind="element" annotationScope="local" /> </appinfo> </annotation> </element> <complexType name="ElementASIType"> <sequence> <element name="fieldName" type="string" /> <element name="fieldType" type="string" /> </sequence> </complexType> <element name="AttributeASI" type="eis2:AttributeASIType"> <annotation> <appinfo source="commonj.emd.asi"> <emd:annotationType xmlns:emd="commonj.emd.asi"

Page 109 of 114


annotationKind="attribute" annotationScope="local" /> </appinfo> </annotation> </element> <complexType name="AttributeASIType"> <sequence> <element name="fieldName" type="string" /> <element name="fieldType" type="string" /> </sequence> </complexType> </schema>

15.3. Sample Business Object Schema

The PurchaseOrder schema from the XML Schema primer is used as an example. <?xml version="1.0" encoding="UTF-8"?> <schema xmlns="http://www.w3.org/2001/XMLSchema" xmlns:po="http://www.mycompany.com" targetNamespace="http://www.mycompany.com"> <annotation> <documentation xml:lang="en"> Purchase order schema example from XML Schema Part 0: Primer Purchase order schema for Example.com. Copyright 2000 Example.com. All rights reserved. </documentation> <appinfo source="commonj.emd.asi"> <emd:annotationSet xmlns:emd="commonj.emd.asi" asiNSURI="http://www.eis1.com/asi" asiSchemaLocation="eis1Schema.xsd"/> </appinfo> <appinfo source="commonj.emd.asi"> <emd:annotationSet xmlns:emd="commonj.emd.asi" asiNSURI="http://www.eis2.com/asi" asiSchemaLocation="eis2Schema.xsd"/> </appinfo> </annotation> <element name="purchaseOrder" type="po:PurchaseOrderType"/> <element name="comment" type="string"/> <complexType name="PurchaseOrderType"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:BusinessObjectASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:ObjectName>eis1.PurchaseOrder1</ns1:ObjectName> </ns1:BusinessObjectASI> </appinfo> </annotation> <sequence> <element name="shipTo" type="po:USAddress"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getShipToAddress</ns1:getMethodName> <ns1:setMethodName>setShipToAddress</ns1:setMethodName> </ns1:ElementASI> </appinfo> <appinfo source="http://www.eis2.com/asi"> <ns2:ElementASI xmlns:ns2="http://www.eis2.com/asi"> <ns2:fieldName>shipAddress</ns2:fieldName>

Page 110 of 114


<ns2:fieldType>shipAddressType</ns2:fieldType> </ns2:ElementASI> </appinfo> </annotation> </element> <element name="billTo" type="po:USAddress"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getBillToAddress</ns1:getMethodName> <ns1:setMethodName>setBillToAddress</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> <element minOccurs="0" ref="po:comment"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getComment</ns1:getMethodName> <ns1:setMethodName>setComment</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> <element name="items" type="po:Items"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getItems</ns1:getMethodName> <ns1:setMethodName>setItems</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> </sequence> <attribute name="orderDate" type="date"/> </complexType> <complexType name="USAddress"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:BusinessObjectASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:ObjectName>eis1.USAddress</ns1:ObjectName> </ns1:BusinessObjectASI> </appinfo> </annotation> <sequence> <element name="first_name" type="string"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getFirstName</ns1:getMethodName> <ns1:setMethodName>setFirstName</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> <element name="last_name" type="string"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getLastName</ns1:getMethodName> <ns1:setMethodName>setLastName</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> <element name="street" type="string"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi">

Page 111 of 114


<ns1:getMethodName>getStreet</ns1:getMethodName> <ns1:setMethodName>setStreet</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> <element name="city" type="string"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getCity</ns1:getMethodName> <ns1:setMethodName>setCity</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> <element name="state" type="string"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getState</ns1:getMethodName> <ns1:setMethodName>setState</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> <element name="zip" type="string"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getZip</ns1:getMethodName> <ns1:setMethodName>setZip</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> </sequence> <attribute fixed="US" name="country" type="NMTOKEN"/> </complexType> <complexType name="Items"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:BusinessObjectASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:ObjectName>eis1.Items</ns1:ObjectName> </ns1:BusinessObjectASI> </appinfo> </annotation> <sequence> <element maxOccurs="unbounded" minOccurs="0" name="item"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getItem[int]</ns1:getMethodName> <ns1:setMethodName>setItem[int]</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> <complexType> <sequence> <element name="partNum" type="string"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getPartNum</ns1:getMethodName> <ns1:setMethodName>setPartNum</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> <element name="productName" type="string"> <annotation>

Page 112 of 114


<appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getProductName</ns1:getMethodName> <ns1:setMethodName>setProductName</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> <element name="quantity"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getQuantity</ns1:getMethodName> <ns1:setMethodName>setQuantity</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> <simpleType> <restriction base="int"> <maxExclusive value="100"/> </restriction> </simpleType> </element> <element name="USPrice" type="decimal"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getPrice</ns1:getMethodName> <ns1:setMethodName>setPrice</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> <element minOccurs="0" ref="po:comment"> </element> <element minOccurs="0" name="shipDate" type="string"> <annotation> <appinfo source="http://www.eis1.com/asi"> <ns1:ElementASI xmlns:ns1="http://www.eis1.com/asi"> <ns1:getMethodName>getShipDate</ns1:getMethodName> <ns1:setMethodName>setShipDate</ns1:setMethodName> </ns1:ElementASI> </appinfo> </annotation> </element> </sequence> </complexType> </element> </sequence> </complexType> <simpleType name="SKU"> <restriction base="string"/> </simpleType> </schema>

Page 113 of 114


16. References [1] J2EE Connector Architecture, Version 1.5 specification [2] Next-Generation data programming: Service Data Objects [3] XML schema [4] RFC 2396 Uniform Resource Identifiers (URI): General Syntax

Page 114 of 114

Documents

Enterprise Metadata Discovery Specificationpublic.dhe.ibm.com/software/dw/library/j-emd/EnterpriseMetadata... · To enable resource adapters to provide this capability there needs