Enterprise Metadata Discovery Authors

Enterprise Metadata Discovery Specification
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.html
or 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.
Page 1 of 114
Enterprise Metadata Discovery Specification
Table of Contents
1. Introduction ...................................................................................................................5
1.1.
1.2.
1.3.
1.4.
1.5.
Overview ........................................................................................................................................5
Scope ..............................................................................................................................................5
Target audience ..............................................................................................................................6
Organization...................................................................................................................................6
Document conventions...................................................................................................................6
2. Overview.........................................................................................................................7
2.1.
2.2.
2.3.
Terms and Definitions....................................................................................................................7
Rationale ........................................................................................................................................8
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 2 of 114
Enterprise Metadata Discovery Specification
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
7.4. Tool requirements ........................................................................................................................57
7.5. Discovery service requirements ...................................................................................................57
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
9.5. Tool requirements ........................................................................................................................80
9.6. Discovery service requirements ...................................................................................................80
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 3 of 114
Enterprise Metadata Discovery Specification
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 4 of 114
Enterprise Metadata Discovery Specification
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 5 of 114
Enterprise Metadata Discovery Specification
•
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:
•
•
•
•
•
•
1.4.
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
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 6 of 114
Enterprise Metadata Discovery Specification
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 7 of 114
Enterprise Metadata Discovery Specification
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)
Page 8 of 114
Enterprise Metadata Discovery Specification
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 9 of 114
Enterprise Metadata Discovery Specification
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.
Container-Component
Contract
The Tooling generates the
service implementation that
can be used by other
applications
Application
Component
Service Interface
Client
API
Resource Adapter
EMD
Application
Server
Runtime
EMD
System
Contract
Discovery
Metadata
Edit
EIS Specific Interface
EIS
Figure 3.1: The EMD Architecture
The four components of the EMD specification are:
Page 10 of 114
EAI
Tooling
Tooling
Enterprise Metadata Discovery Specification
• 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 11 of 114
Enterprise Metadata Discovery Specification
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 Open Group
Application Meta
Model
Text Type
Text Type
Orientation
Global orientation
Unicode
Windows
Valid values
Memory
representation and
display ordering
Base direction or
paragraph
direction
Logical and visual
•
Reading order
•
•
•
•
•
Symmetric
Numeral shape
Page 12 of 114
Symmetrical
swapping
National numbers
Mirroring
Decimal forms
Swapping of
symmetric pairs
National and
nominal digits
•
•
•
•
•
Implicit or
logical
Visual
LTR
RTL
Contextual
LTR
Contextual
RTL
True
False
Nominal
National
Contextual
Enterprise Metadata Discovery Specification
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.
recommended canonical form is:
• Text type: implicit
• Orientation: LTR
• Symmetric: swapped
• Numeral shape: nominal
• Text shape: nominal
Page 13 of 114
The
Enterprise Metadata Discovery Specification
4.
4.1.
Roles/Scenarios
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 14 of 114
Enterprise Metadata Discovery Specification
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 15 of 114
Enterprise Metadata Discovery Specification
(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 reconfigured 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 16 of 114
Enterprise Metadata Discovery Specification
4.4.
Sample Enterprise Application
Process Implementation
by Developer
Customer Source
Customer Source MDB
CRM
Resource
Adapter
CRM
System
ERP
Resource
Adapter
ERP
System
CRM Listener
Implementation
Implementation
Customer Sink
Implementation
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 17 of 114
Enterprise Metadata Discovery Specification
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 18 of 114
Enterprise Metadata Discovery Specification
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 19 of 114
Enterprise Metadata Discovery Specification
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 20 of 114
Enterprise Metadata Discovery Specification
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 21 of 114
Enterprise Metadata Discovery Specification
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 22 of 114
Enterprise Metadata Discovery Specification
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 23 of 114
Enterprise Metadata Discovery Specification
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 24 of 114
Enterprise Metadata Discovery Specification
// 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 25 of 114
Enterprise Metadata Discovery Specification
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 26 of 114
Enterprise Metadata Discovery Specification
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 27 of 114
Enterprise Metadata Discovery Specification
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 28 of 114
Enterprise Metadata Discovery Specification
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
6. Configure
selected nodes.
5. Select metadata
nodes for import.
7. Configure
entire selection.
8. Import selection
into a service
description.
3. Use Metadata Tree to
query EIS and get a filtered
tree representation of its
metadata.
4. Navigate the tree,
expanding various
metadata nodes.
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 29 of 114
Enterprise Metadata Discovery Specification
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().
Page 30 of 114
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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 32 of 114
Enterprise Metadata Discovery Specification
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 33 of 114
Enterprise Metadata Discovery Specification
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 34 of 114
Enterprise Metadata Discovery Specification
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 prefetching 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 suboptimal 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 35 of 114
Enterprise Metadata Discovery Specification
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 36 of 114
Enterprise Metadata Discovery Specification
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 37 of 114
Enterprise Metadata Discovery Specification
• 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 38 of 114
Enterprise Metadata Discovery Specification
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 39 of 114
Enterprise Metadata Discovery Specification
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 40 of 114
Enterprise Metadata Discovery Specification
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
if (!adapterType.hasMetadataConnectionTypes())
//Obviously, a real tool would
//want more robust error handling. We just
System.out.println("This adapter type does
return;
}
connection types
{
return here.
not support metadata discovery");
// 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 41 of 114
Enterprise Metadata Discovery Specification
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 42 of 114
Enterprise Metadata Discovery Specification
// - 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 43 of 114
Enterprise Metadata Discovery Specification
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 44 of 114
Enterprise Metadata Discovery Specification
•
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 45 of 114
Enterprise Metadata Discovery Specification
• 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 46 of 114
Enterprise Metadata Discovery Specification
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 discoveryservice.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 47 of 114
Enterprise Metadata Discovery Specification
• 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
o
o
commonj.connector.metadata.discovery.AdapterType
commonj.connector.metadata.discovery.AdapterTypeSummary
commonj.connector.metadata.discovery.MetadataDiscovery
If service discovery is supported then implementations must be supplied for the following
interfaces:
o
o
o
o
o
o
commonj.connector.metadata.discovery.MetadataImportConfiguration
commonj.connector.metadata.discovery.MetadataObject
commonj.connector.metadata.discovery.MetadataObjectIterator
commonj.connector.metadata.discovery.MetadataObjectResponse
commonj.connector.metadata.discovery.MetadataSelection
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 48 of 114
Enterprise Metadata Discovery Specification
• 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 49 of 114
Enterprise Metadata Discovery Specification
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 50 of 114
Enterprise Metadata Discovery Specification
• 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 51 of 114
Enterprise Metadata Discovery Specification
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 52 of 114
Enterprise Metadata Discovery Specification
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 53 of 114
Enterprise Metadata Discovery Specification
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)
Page 54 of 114
Enterprise Metadata Discovery Specification
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 55 of 114
Enterprise Metadata Discovery Specification
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
generateDataBinding. This returns an array of DataBindingDescriptions.
factory
method
called
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
o
o
o
o
JDK 1.4 or later (depends on the target runtime environment)
J2EE CA 1.0/1.5
SDO 2.0
EMD 1.0
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 56 of 114
Enterprise Metadata Discovery Specification
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 57 of 114
Enterprise Metadata Discovery Specification
• 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 58 of 114
Enterprise Metadata Discovery Specification
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 59 of 114
Enterprise Metadata Discovery Specification
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 60 of 114
Enterprise Metadata Discovery Specification
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 61 of 114
Enterprise Metadata Discovery Specification
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 62 of 114
Enterprise Metadata Discovery Specification
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 63 of 114
Enterprise Metadata Discovery Specification
• 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 recreatable 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 64 of 114
Enterprise Metadata Discovery Specification
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 65 of 114
Enterprise Metadata Discovery Specification
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 66 of 114
Enterprise Metadata Discovery Specification
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 67 of 114
Enterprise Metadata Discovery Specification
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 68 of 114
Enterprise Metadata Discovery Specification
Event Type
PROPERTY_VALUE_CHANGE
Event
Description
Event Source
New Value
Old Value
The old value of
the property
PropertyDescriptor
The new current
value of the
property
The new object
array of property
values
null
PropertyDescriptor
null
null
Property
null
null
Property
null
null
Property
The old array of
recommended
property values
null
PropertyGroup
The new array
of recommended
property values
The child
property
descriptor that
was added
null
Fired when the value
of a single valued
property changes
Fired when the value
of a multi valued
property changes.
Fired when a
property descriptor
becomes enabled.
Fired when a
property descriptor
becomes disabled.
Fired when a
property value
becomes valid.
Fired when a
property value
becomes invalid.
Fired when the set of
valid values for a
property change.
Fired when a
property descriptor is
added to a property
group.
Fired when a
property descriptor is
removed from a
property group.
Fired when all the
contents of a property
group are removed.
SingleValuedProperty
PropertyGroup
null
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.
The old array of
property
descriptors that
were part of the
property group.
TREE_PROPERTY_SELECTED
Fired when a node
property is selected.
Fired when a node
property is
deselected.
NodeProperty
Boolean.TRUE
Boolean.FALSE
NodeProperty
Boolean.FALSE
Boolean.TRUE
PROPERTY_VALUE_CHANGE
PROPERTY_ENABLE
PROPERTY_DISABLE
PROPERTY_VALUE_VALID
PROPERTY_VALUE_INVALID
PROPERTY_VALID_VALUES_CHANGE
PROPERTYGROUP_ADD_CHILD
PROPERTYGROUP_REMOVE_CHILD
PROPERTYGROUP_REMOVE_ALL
TREE_PROPERTY_DESELECTED
Page 69 of 114
MultiValuedProperty
PropertyGroup
The old object
array of property
values
null
The child property
descriptor that was
removed
Enterprise Metadata Discovery Specification
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 70 of 114
Enterprise Metadata Discovery Specification
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 71 of 114
Enterprise Metadata Discovery Specification
9.
9.1.
Data Handling
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 72 of 114
Enterprise Metadata Discovery Specification
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 73 of 114
Enterprise Metadata Discovery Specification
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 74 of 114
Enterprise Metadata Discovery Specification
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 75 of 114
Enterprise Metadata Discovery Specification
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 76 of 114
Enterprise Metadata Discovery Specification
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 77 of 114
Enterprise Metadata Discovery Specification
• 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 78 of 114
Enterprise Metadata Discovery Specification
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 79 of 114
Enterprise Metadata Discovery Specification
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 80 of 114
Enterprise Metadata Discovery Specification
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 81 of 114
Enterprise Metadata Discovery Specification
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 82 of 114
Enterprise Metadata Discovery Specification
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.
Page 83 of 114
Enterprise Metadata Discovery Specification
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
public class AccountService {
public AccountDataObject getAccount(CustomerDataObject customer){
ConnectionFactory connectionFactory = getConnectionFactory();
// Create and configure InteractionSpec
ERPInteractionSpec interactionSpec = new ERPInteractionSpec();
interactionSpec.setProperty1(…);
interactionSpec.setProperty2(…);
// Create instance of the Interaction
Connection connection = connectionFactory.getConnection();
Interaction interaction = connection.createInteraction();
// Instantiate data bindings
RecordDataBinding inputBinding = new CustomerBindingImpl();
RecordDataBinding outputBinding = new AccountBindingImpl();
// Set service argument on the input data binding
inputBinding.setDataObject(customer);
if(supportsInputOutputExecute)
interaction.execute(interactionSpec, inputBinding,outputBinding);
return (AccountDataObject)outputBinding.getDataObject();
}
…
public ConnectionFactory getConnectionFactory(){
// Create ConnectionFactory in the non-managed environment
ManagedConnectionFactory mcf = new ERPManagedConnectionFactory();
mcf.setProperty1(…);
mcf.setProperty2(…);
ConnectionFactory cf = mcf.createConnectionFactory();
// OR lookup ConnectionFactory managed
// ConnectionFactory cf = context.lookup(“eis/ERPConnectionFactory”);
}
}
Page 84 of 114
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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 discoveryservice.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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
ManagedConnectionFactory
by
invoking
the
the
synchronizeFromPropertyGroupToManagedConnectionFactory
method
on
OutboundConnectionType. The tool can then save the change to the service interface.
Page 97 of 114
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
<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
Enterprise Metadata Discovery Specification
<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
Enterprise Metadata Discovery Specification
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.
the ASI may differ between SAP RFC and SAP BAPI.
For example,
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
Enterprise Metadata Discovery Specification
<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:
&lt;schema ...&gt;
&lt;annotation&gt;
&lt;appinfo source=&quot;commonj.connector.asi&quot;&gt;
&lt;asi:annotationSet xmlns:asi=&quot;commonj.connector.asi&quot;
asiNSURI=&quot;http://www.eis.com/asi&quot;
asiSchemaLocation=&quot;http://www.eis.com/asi/eisSchema.xsd&quot;/&gt;
&lt;/appinfo&gt;
&lt;/annotation&gt;
...
&lt;/schema&gt;
</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
Enterprise Metadata Discovery Specification
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:
&lt;element name=&quot;BusinessObjectASI&quot;
type=&quot;eis1:BusinessObjectASIType&quot;&gt;
&lt;annotation&gt;
&lt;appinfo source=&quot;commonj.connector.asi&quot;&gt;
&lt;asi:annotationType xmlns:asi=&quot;commonj.connector.asi&quot;
annotationKind=&quot;complexType&quot; annotationScope=&quot;global&quot;
/&gt;
&lt;/appinfo&gt;
&lt;/annotation&gt;
&lt;/element&gt;
&lt;complexType name=&quot;BusinessObjectASIType&quot;&gt;
&lt;sequence&gt;
&lt;element name=&quot;ObjectName&quot; type=&quot;string&quot; /&gt;
&lt;/sequence&gt;
&lt;/complexType&gt;
&lt;element name=&quot;ElementASI&quot; type=&quot;eis1:ElementASIType&quot;&gt;
&lt;annotation&gt;
&lt;appinfo source=&quot;commonj.connector.asi&quot;&gt;
&lt;asi:annotationType xmlns:asi=&quot;commonj.connector.asi&quot;
annotationKind=&quot;element&quot; annotationScope=&quot;local&quot;
/&gt;
&lt;/appinfo&gt;
&lt;/annotation&gt;
&lt;/element&gt;
&lt;complexType name=&quot;ElementASIType&quot;&gt;
&lt;sequence&gt;
&lt;element name=&quot;getMethodName&quot; type=&quot;string&quot; /&gt;
&lt;element name=&quot;setMethodName&quot; type=&quot;string&quot; /&gt;
&lt;/sequence&gt;
&lt;/complexType&gt;
</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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
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
Enterprise Metadata Discovery Specification
<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
Enterprise Metadata Discovery Specification
<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
Enterprise Metadata Discovery Specification
<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
Enterprise Metadata Discovery Specification
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