Hp Man CIT9.30 SDK PDF

8/10/2019 Hp Man CIT9.30 SDK PDF

1/74

Document Release Date: June 2011Software Release Date: June 2011

HP Connect-It

Software version: 9.30

SDK


2/74

Legal NoticesCopyright Notices

Copyright 1994-2011 Hewlett-Packard Development Company, L.P.

Restricted Rights Legend

Confidential computer software.

Valid license from HP required for possession, use or copying.

Consistent with FAR 12.211 and 12.212, Commercial Computer Software, Computer Software Documentation, andTechnical Data for Commercial Items are licensed to the U.S. Government under vendor's standard commercial license.

Warranty

The only warranties for HP products and services are set forth in the express warranty statements accompanyingsuch products and services.

Nothing herein should be construed as constituting an additional warranty.

HP shall not be liable for technical or editorial errors or omissions contained herein.

The information contained herein is subject to change without notice.

For information about third-party and/or open source license agreements, or to view open source code, use one of thefollowing ways:

nIn the ThirdPartydirectory of the software installation CD-ROM

nIn the directories in which the binary files of the third-party and/or open source tools are located after installationof the software.

n Through the component's url indicated in the Open Source and Third-Party Software License Agreementsguide

Trademark Notices

nAdobe,Adobe logo, Acrobat and Acrobat Logo are trademarks of Adobe Systems Incorporated.

nCorel and Corel logo are trademarks or registered trademarks of Corel Corporation or Corel CorporationLimited.

nJava is a registered trademark of Oracle and/or its affiliates.

n Microsoft,Windows,Windows NT,Windows XP, Windows Mobile and Windows Vista are U.S. registeredtrademarks of Microsoft Corporation.

nOracle is a registered trademark of Oracle Corporation and/or its affiliates.

nUNIX is a registered trademark of The Open Group.

Build number: 312


3/74

Introduction . . . . . . . . . . . . . . . . . . . . . . . 7Who is this guide intended for? . . . . . . . . . . . . . . . . . 7Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 7General information . . . . . . . . . . . . . . . . . . . . . 8

Chapter 1. Data exchange . . . . . . . . . . . . . . 9

Data and data types . . . . . . . . . . . . . . . . . . . . . 9Models . . . . . . . . . . . . . . . . . . . . . . . . . . 10

Chapter 2. Design-Time . . . . . . . . . . . . . . . 15DesignTimeFactory interface . . . . . . . . . . . . . . . . . 15ObjectTypeProvider interface . . . . . . . . . . . . . . . . . 18

Chapter 3. Runtime . . . . . . . . . . . . . . . . . . 21Outbound communications . . . . . . . . . . . . . . . . . . 21Inbound communications . . . . . . . . . . . . . . . . . . . 25

Chapter 4. Deployment . . . . . . . . . . . . . . . . 27

Chapter 5. Configuration . . . . . . . . . . . . . . . 29

HP Connect-It 9.30 - SDK | 3

Table of Contents


4/74

Description file . . . . . . . . . . . . . . . . . . . . . . . 29Icon file . . . . . . . . . . . . . . . . . . . . . . . . . . 30Configuration file . . . . . . . . . . . . . . . . . . . . . . 30

Wizard file . . . . . . . . . . . . . . . . . . . . . . . . . 30JVM configuration file . . . . . . . . . . . . . . . . . . . . 32

Chapter 6. Packaging . . . . . . . . . . . . . . . . 33Java archive . . . . . . . . . . . . . . . . . . . . . . . . 34

Chapter 7. Extension . . . . . . . . . . . . . . . . . 35Interface com.hp.ov.cit.connector.spi.ContainerContext . . . . . . . 35com.hp.ov.cit.connector.spi.designtime.ObjectTypeProviderEx class . . 36

Chapter 8. Use . . . . . . . . . . . . . . . . . . . . 39Authorization certificate . . . . . . . . . . . . . . . . . . . 39Generate a key . . . . . . . . . . . . . . . . . . . . . . . 39

I. Appendix . . . . . . . . . . . . . . . . . . . . . . 41

Chapter 9. Wizard file . . . . . . . . . . . . . . 43General structure . . . . . . . . . . . . . . . . . . . . 43Wizard element . . . . . . . . . . . . . . . . . . . . 43Include element . . . . . . . . . . . . . . . . . . . . 44

Page element . . . . . . . . . . . . . . . . . . . . . . 45Property element . . . . . . . . . . . . . . . . . . . . 46Control element . . . . . . . . . . . . . . . . . . . . 47Linebreak and separator elements . . . . . . . . . . . . . 50Transition element . . . . . . . . . . . . . . . . . . . 51Script attribute . . . . . . . . . . . . . . . . . . . . . 51Included attribute . . . . . . . . . . . . . . . . . . . . 52Functions . . . . . . . . . . . . . . . . . . . . . . . 52

Chapter 10. Configuration file . . . . . . . . . . 55Configuration element . . . . . . . . . . . . . . . . . . 56Property element . . . . . . . . . . . . . . . . . . . . 56Definition element . . . . . . . . . . . . . . . . . . . 56Export element . . . . . . . . . . . . . . . . . . . . . 57Class element . . . . . . . . . . . . . . . . . . . . . 57

Property types . . . . . . . . . . . . . . . . . . . . . 57

4 | HP Connect-It 9.30 - SDK


5/74

Chapter 11. JVM configuration file . . . . . . . 59jvmConfiguration element . . . . . . . . . . . . . . . . 60

jarLocation element . . . . . . . . . . . . . . . . . . . 60Jars element . . . . . . . . . . . . . . . . . . . . . . 61jvmOptions element . . . . . . . . . . . . . . . . . . . 63Import element . . . . . . . . . . . . . . . . . . . . 63

Chapter 12. Database description file . . . . . . 65File structure . . . . . . . . . . . . . . . . . . . . . 65

Properties . . . . . . . . . . . . . . . . . . . . . . . 65Example . . . . . . . . . . . . . . . . . . . . . . . 68Additional information . . . . . . . . . . . . . . . . . . 69

Chapter 13. Java code . . . . . . . . . . . . . . 71JavaBeans . . . . . . . . . . . . . . . . . . . . . . . 71Logging . . . . . . . . . . . . . . . . . . . . . . . . 72

Internationalization . . . . . . . . . . . . . . . . . . . 73

Index . . . . . . . . . . . . . . . . . . . . . . . . . 75

http://-/?-http://-/?-


6/74



7/74

The Connect-It Development Kit enables you to develop and implement yourown connectors.This development kit uses a Java interface based on the J2EEConnector Architecture (1.5) standard. The JCA standard defines a set of Javainterfaces used to simplify the integration of enterprise applications (ERP,database applications, etc).

Who is this guide intended for?

This guide is destined for developers who have sufficient expertise in Java andthe JCA standard. For more information about this standard, consult thefollowing Web site: J2EE Connector Architecture[http://java.sun.com/j2ee/connector].

Terminology

The following acronyms are used throughout this guide:

n JCA: J2EE Connector Architecture

n RA: Resource Adapter

n EIS: Enterprise Information System

n CCI: Common Client Interface


Introduction
http://java.sun.com/j2ee/connectorhttp://java.sun.com/j2ee/connector


8/74

n SPI: Service Provider Interface

n JDBC: Java Database Connectivity

General information

The API defines an extension to the JCA 1.5 API which enables the connectorto be integrated into the application. The following diagram shows how thisworks:

The communication mode with the connector depends on the information system(EIS) to which it is connected.

Two communication possibilities exist:

n Outbound communications (synchronous)

The client initiates the data exchange. This occurs, for example, when aquery is sent to a database.

n Inbound communications (asynchronous)

The EIS initiates the data exchange. The connector is in listening mode.This is what takes place for messaging.

SPI ExtensionsThe SDK supplies an extension to the SPI classes to enable the support ofmetadata descriptions.

CCI ExtensionsThe SDK supplies a client layer that can manage access to a system, whetherit be a relational database or not. This extension groups functions from thestandard CCI API and the JDBC API.



9/74

The goal of a connector designed using the SDK is to standardize data exchangewith information systems. Data exchanges include sending and receiving data.

Data and data types

Before data can be exchanged, the structure of the data must be known. Thisstructure is what is called metadata. The SDK requires that the structure ofthe data be known before any operations are done using the data. This is donevia two interfaces:

com.hp.ov.cit.connector.cci.ObjectRecord - represents a specific piece ofdata.

And

com.hp.ov.cit.connector.cci.ObjectType - represents the structure that a

set of related data must have.

Since it is required to describe each piece of data that is sent or received, anObjectRecordinstance is linked to its ObjectTypedescription.

Data supplied via a connector are generally organized within a hierarchy orgraph. Their metadata is also hierarchical. Metadata is said to be 'complex'when it contains other metadata. The 'child' metadata make up the fields ofthe data. Metadata is said to be 'simple' when it does not contain other metadata.

This metadata contains no fields.An ObjectRecordgraph is composed of:


Data exchange1


10/74

n A single ObjectRecordroot data item.

n Each of the ObjectRecordscan be accessed by traversing the fieldsrecursively.

Models

The SDK provides two distinct data models described by the ObjectType,ObjectRecordpair. These models are the Class/Instancemodel and theXMLSchema/XMLmodel. Only one model is possible per connector.

Class/Instance modelThis model is an object representation of a data structure. This model is basedon the Java notions of class and instance.

Class

A class has a name and belongs to a package which forms its namespace. It ismade up of fields that are associated with classes.

Within this model, a class makes up the metadata. It can be accessed via theObjectTypeinterface and has the following methods:

public String getName();public String getNamespace();

public Class getObjectClass();

public boolean isSimple();public Field getField(String fieldName);public Field[] getFields();

A field accessed by the com.hp.ov.cit.connector.cci.Fieldinterface containsits own information and the information that is related to its class. A class hasthe following characteristics:

n It can be modified

n It can have a default value

n It can appear several times and when it appears in a list it is described asbeing indexed

n It can be required to have a value

This is done through the Fieldinterface via the following methods:

public String getName();public ObjectType getType();public Object getDefault();

public boolean isIndexed();



11/74

public boolean isReadOnly();public boolean isRequired();

Instance

An instance is associated with a class and contains values for one or more ofits fields.

Within this model, an instance forms a piece of data. It is represented via theObjectRecordinterface and has the following methods:

public Object get(String fieldName);public Object get(String fieldName, int fieldIndex);public void set(String fieldName, Object value);

public void set(String fieldName, int fieldIndex, Object value);public void remove(String fieldName);public void remove(String fieldName, int fieldIndex);

Simple types

The following table provides the list of Java simple types that are supportedby the SDK.

java.lang.Booleanjava.lang.Bytejava.lang.Shortjava.lang.Integerjava.lang.Longjava.lang.Floatjava.lang.Doublejava.lang.String

java.util.Datebyte[]char[]

Example

Consider the data model below:

A|- String|- int|- B|- String|- C*|- boolean

Business classes are thus represented as:

public class A{

private String stringField = "This is a string";private int intField;



12/74

private B bField;}

public class B

{private String stringField;private List listOfCField;}

public class C{private boolean booleanField;}

Operations on types can be done as follows:

ObjectType objectTypeA = ...;Field field = objectTypeA.getField("stringField");boolean isSimple = field.getType().isSimple(); // trueObject defaultValue = field.getDefault(); // "This is a string"...field = objectTypeA.getField("bField");isSimple = field.isSimple(); // falseObjectType objectTypeB = field.Type();field = objectTypeB.getField("listOfCField");boolean isIndexed = field.isIndexed(); //true;

Data can be stored in the following manner:

ObjectRecord objectA = ...;ObjectRecord objectB = ...;ObjectRecord objectC = ...;

objectA.set("intField", 5);objectA.set("bField", objectB);

java.util.List list = new java.util.ArrayList();list.add(objectC);objectB.set("listOfCField", list);

XMLSchema/XML modelThis representation model is adapted to systems handling XML data. Metadata

is formed from a set of independent XML schemas. This model limits the useof the interfaces described above. In this case, the only pertinent methods ofthe ObjectTypeinterface are:

public String getName();public String getNamespace();

public boolean isXSD();public org.w3c.dom.ls.LSInput[] getXSD();



13/74

This model also supposes that metadata identified by its name and namespaceis always simple. This means that it cannot contain any fields, and may onlycontain one or more XML schemas.

Data itself can be accessed in the ObjectRecordinterface via the followingmethods:

public void readXML(org.w3c.dom.ls.LSInput input);public void writeXML(org.w3c.dom.ls.LSOutput output);

These methods enable the XML representation to be imported or exported:

n org.w3c.dom.ls.LSInput - represents an input source for the XML data.

n org.w3c.dom.ls.LSOutput - represents an output source for the XML data.



14/74



15/74

This section describes elements that are used by a connector to connect to anEIS and discover its metadata.

DesignTimeFactory interface

The com.hp.ov.cit.connector.spi.designtime.DesignTimeFactory interfacecentralizes all the information required to:n Obtain a connection

n Describe the structure of the data exchanges with the EIS

Communication modeThe methods

public boolean supportsOutbound()

And

public boolean supportsInbound()

are used to determine the communication mode used by the EIS. WithinConnect-It these two modes are exclusive. A connector implementation can onlysupport one mode at a time.


Design-Time2


16/74

Design-timeconnectionData exchange types must be described regardless of the communication mode.To do this a connection is used, whether it be a real one or not. For outbound

communications it is also possible that this connection be different from theconnection that is used for the data exchange itself. For example, in the caseof a web service, metadata is described using a WSDL file that can be accessedvia an FTP connection whereas communication with the web service is doneusing the http protocol.

The API of the DesignTimeFactoryclass provides the following methods:

n public boolean requiresSeparateMetaDataConnection()

Determines if the EIS distinguishes between the two connection types.Thismethod is not used for inbound communications.

n public javax.resource.cci.ConnectionSpeccreateMetaDataConnectionSpec()

This method returns a JavaBean implementation of the ConnectionSpecinterface. The object contains client-specific information such as "user" and"password" that are used to connect during the design-time phase. The

method involved for outbound communications that do not differentiatedesign-time connections from run-time connections is:

n public javax.resource.cci.ConnectionSpec createConnectionSpec()

For example, the url must be known if metadata is accessed via an httpconnection:

package com.myeis;

import java.net.URL;

import javax.resource.cci.ConnectionSpec;

public class MyEISConnectionSpec implements ConnectionSpec{private URL url;

public URL getUrl(){return url;}

public void setUrl(String url){this.url = url;}}

Once the connection information is retrieved, the metadata can be described.



17/74

Retrieving metadataThe method

public ObjectTypeProvider

getObjectTypeProvider(javax.resource.cci.ConnectionSpecmetaDataConnSpec)

returns an object which is used to obtain the description of the data that isexchanged with the EIS. The required connection information makes up itsparameters.

Example The operations described above are shown in the following diagram.The diagramshows an outbound communication which requiring specific connection to accessthe metadata:

A client queries the DesignTimeFactoryto see if the connector supports theoutbound communication. If it does, it queries to see if the connection to themetadata is distinct from the connection used to exchange data. Depending onthe response, the client will either call the createMetaDataConnectionSpec

method or the createConnectionSpecmethod in order to retrieve aconnection's description. The client then sets the properties of the method andcalls the DesignTimeFactoryto retrieve the ObjectTypeProviderwhich isused to describe the metadata.



18/74

ObjectTypeProvider interface

The com.hp.ov.cit.connector.spi.designtime.ObjectTypeProviderinterfaceis used to describe EIS data types.This description may be infinite. For example,an A data type may contain a B data type itself containing an A data type. Toavoid recursion problems, instead of describing data types in one block, theinterface is based on a navigable model.This makes it possible to find first leveldata first. Then, as subsequent calls are made to the interface, the other levelsof data can be described. As these types are retrieved via a connection, callingthe method:

public void close()closes the connection.

The following methods are used to describe first-level metadata:

public java.util.List getReceivedTypes();public java.util.List getRequestTypes();public java.util.List getResponseTypes();

Depending on the EIS type and communication mode (inbound or outbound),

these methods will need to be supported or not supported. Supported methodsare implemented as follows:

public java.util.List getXXXTypes(){java.util.List types = new java.util.ArrayList();types.add(new MyEISObjectType());...return types;

}For unsupported methods:

public java.util.List getXXXTypes() throws javax.resource.NotSupportedException{throw new javax.resource.NotSupportedException();}

Inbound communicationsOnly the following method is supported in this mode:

public java.util.List getReceivedTypes()

This method must return the list of events that could be received from the EIS.



19/74

Outbound communicationsTwo types of data exchange modes are supported:

n Request/response (such as an HTTP request)

n Query (such as an SQL SELECT query)Data types from queries are retrieved via:

public java.util.List getRequestTypes()

This method must return the list of query types that could be sent to the EIS.

Once a query produces a response, such as when the getPurchaseOrder(intid)function returns a "PurchaseOrder" object, the following method must be

used to describe the expected response type:public java.util.List getResponseTypes()

Once a query leads to its response, such as when the"getPurchaseOrders(PurchaseOrderType)" function returns a "PurchaseOrder"object, the following method:

public java.util.List getReceivedTypes()

is used. Instead of sending a query containing data, the EIS is queried to findelements via their metadata.

Note that the getResponseTypes()method is not supported separately. AnEIS response cannot be received if a query has not been sent to it.

Navigation

Once the first level types have been retrieved, the following method is calledto return the sub-types of the other levels:

public ObjectType getType(String namespace, String name)

Using the information from the namespace, namecouple sent as parameterby the caller, it is possible to know the level that is to be described. Once a levelis terminal, the method must return null.



20/74



21/74

This section describes elements that are used by a connector to connect to anEIS and exchange data.

Outbound communications

ConfigurationThe key class of this communication mode is the one that implements thejavax.resource.spi.ManagedConnectionFactoryinterface.This class mustalso implement thejavax.resource.spi.ResourceAdapterinterface. Asoutlined by the JCA specifications, this class must be a JavaBean. The fieldsof this JavaBean object represent information that is required by the connectionregardless of the client. For example, for a database accessed via an ODBC

connection, the name of this database is required regardless of the client.package com.mycompany.myeis;

import javax.resource.spi.ManagedConnectionFactory;import javax.resource.spi.javax.resource.spi.ResourceAdapter

public class MyEISManagedConnectionFactory implements ManagedConnectionFactory, ResourceAdapter{

private String dataSourceName;


Runtime3


22/74

public String getDataSourceName(){return dataSourceName;}

public void setDataSourceName(String dataSourceName){this.dataSourceName = dataSourceName;}

...}

ConnectionClient connection's obtained from a connector built using the SDK complieswith the JCA standard.

Ajavax.resource.cci.ConnectionSpecobject representing the connectioninformation must be retrieved first. This is done as shown in the followingschema:

The client accesses EIS via thejavax.resource.cci.ConnectionFactoryinterface to create a connection from the information that is supplied.To simplifythe example, certain details have been omitted (connection pooling, connectionlistener).



23/74


24/74


25/74

Inbound communications

ConfigurationThe key class of this communication mode is the one that implements thejavax.resource.spi.ResourceAdapterinterface. As outlined by the JCAspecifications, this class must be a JavaBean.The fields of this JavaBean objectrepresent information that is required by the connection regardless of the client.

ConnectionThe class that implements thejavax.resource.spi.ActivationSpecinterfacerepresents the information required to establish a client connection. As for thejavax.resource.spi.ResourceAdapterclass, it must be a JavaBean object.

Exchange

The EIS initiates the exchange. The connector acts as an event listener. Whenevents are received, the connector notifies the client via thejavax.resource.spi.endpoint.MessageEndPointFactoryobject passed asparameter when it was started.This allows it to create aConnectionListenerobject whose interface is:

public interface ConnectionListener extends MessageListener{public void onException(Exception exception);

public ObjectRecord onRecord(ObjectRecord record);}

SchemasRetrieving connection information (design-time):



26/74

Life cycle of the ResourceAdapter class:



27/74

To use the connector with Connect-It you must first create a deployment file.The SDK uses its own deployment descriptor file and not the ra.xmldescriptorfrom the JCA standard.This XML file is based on the context notion introducedby the Springframework. It must be named designtime-beans.xmlandsaved to the root of the connector's JAR archive.

The following information is included:

n Complete name of thecom.hp.ov.cit.connector.spi.designtime.DesignTimeFactory class.

n Complete name of thejavax.resource.spi.ResourceAdapterclass. Foroutbound communications, thejavax.resource.spi.ManagedConnectionFactoryclass is implemented.

An example is given below:


Deployment4


28/74



29/74

A certain number of configuration files are required by Connect-Itin order touse the connector. This name must be unique among all existing Connect-Itconnectors.We recommend that you follow "Java" package naming conventions.In this example we will use the name com.mycompany.myeisfor ourconnector.

Description fileThis is main file for the actual description of the connector. It groups all theproperties related to the connector such as its unique name, the references tofile names described after and its activation key. The extension of this file mustbe .dsc. We recommend that you name the file myeis.dsc.

Example:

{CONNECTORDESCInternalName=com.mycompany.myeisParentInternalName=Application_connectorsName=My EISHTMLHelp=This is a description of my connectorKey=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXIconFile=myeis.bmpSched.CanUsePointer=0Cnx.HasCnx=1

Wizard.File=myeis-wizard.xml


Configuration5


30/74

Java.Class=com.hp.ov.cit.container.RAContainerJava.Configuration.File=myeis-config.xmlJava.JVMConfiguration.File=myeis-jvmconf.xmlJava.HasOptions=1}

Icon file

You must supply a 16x16 bitmap to view an icon in the connectors navigationtree. This file can be named myeis.bmp.

Configuration file

This file contains the set of JavaBeans properties that must be configured bythe user. This file is also used to specify which properties will be included inthe scenario configuration that is exported via this command line:

conitsvc -export[:]

Example of a myeis-config.xmlfile:

URLUser

Wizard file

An XML-format wizard definition file for the connector.



31/74

It is used to describe the pages that are used to configure the connector inConnect-It. It contains a connection definition page. Interface controls arealso described in terms of notions (text, checkbox, button), labels, position, etc.

All JavaBeans properties that must be configured by the user must be in thisfile. The following naming convention must be used:

n The prefix ra_must be added to each property that is related to theimplementation of thejavax.resource.spi.ResourceAdapterinterface.

n The prefix mdcs_must be added to each property that is related to theimplementation of the designtime (metadata)javax.resource.cci.ConnectionSpecinterface.

n The prefix cs_must be added to each property that is related to the

implementation of thejavax.resource.cci.ConnectionSpecinterface.n The prefix as_must be added to each property that is related to the

implementation of thejavax.resource.spi.ActivationSpecinterface.

Example of a myeis-wizard.xmlfile:

Connection

Configure connection to MyEIS

Enter the URL$(GetValue[ra_url])URL25001

1You must specify an URL valueValue

Enter the user name$(GetValue[cs_userName])User2500

1Value

{trConnector}



32/74


33/74

The connector must be packaged with the Connect-It installation in the followingmanner:

Connect-It/||- lib/| |- com.mycompany.myeis/| |- myeis-1.00.jar| |- myeis-3rdparty1.jar| |- myeis-3rdparty2.jar

| |- ...||- config/|- com.mycompany.myeis/|- myeis.bmp|- myeis-jvmconf.xml|- myeis.dsc|- myeis-wizard.xml|- myeis-config.xml

Note:

To ensure that names are unique, the connector's configuration and archive directoriesmust follow the "Java" package naming conventions. The namecom.mycompany.myeisin the example above follows these conventions.


Packaging6


34/74

Java archive

The following structure must be used for the myeis-1.00.jararchive:

myeis-1.00.jar||- designtime-beans.xml||- com/| |- mycompany/| |- myeis/| |- MyEisDesignTimeFactory.class| |- MyEisManagedConnectionFactory.class

| |- MyEisConnectionManager.class| |- ...||- META-INF/| |- Manifest.mf



35/74

Interface com.hp.ov.cit.connector.spi.ContainerContext

When the connector is instantiated via Connect-It, the application provides theimplementation with a specialization of the class used to access specific features ofthe container. This context class provides the following possibilities:

Event listenerIt is possible to receive notifications of execution events concerning theConnect-It scenario. This is done via a listening class using these methods:

public void addContainerListener(ContainerListener listener);public void removeContainerListener(ContainerListener listener);

The SDK has introduced 2 listening class types:

n com.hp.ov.cit.connector.spi.ExecutionListener: Listens for notifications whena scenario starts or stops.

n com.hp.ov.cit.connector.spi.SessionListener: Listens for session opening andclosing notifications for a scenario that is executing.

Access to the scenario path

It is possible to obtain the full path of the scenario executed via the call:


Extension7


36/74

if( simpleType instanceof MyDateObjectType)


37/74

if( simpleType instanceof MyDateObjectType){return "date";}else if( simpleType instanceof MyDatetimeObjectType)

{return "dateTime";}else if( simpleType instanceof MyTimeObjectType){return "time";}else{//sorry ...no additionnal info along the Java class type

return null;}}}



38/74



39/74

Implementing a connector developed using the SDK, is linked to:n An SDK access declaration in the Connect-It authorization certificate.

n A key that has been generated for the connector created using the SDK.

Authorization certificate

The authorization certificate activates:n The runtime that enables the connector created using the SDK to be used.

n The menu used to generate a key for the newly created connector (key usedby the runtime).

Connect-It - User's guide, Installation chapter, Entering the authorizationcertificate.

Generate a key

A key allows the connector to be used.

To generate a key:1 Launch the Connect-It scenario builder

2 SelectJava/ Generate SDK activation key


Use8

3 In the window that is displayed, enter:


40/74

n The name of the connector.

n Its mode (production, consumption).

4 The key that is generated must be copied to the description fileConnect-It Guide - SDK, section Database description file [page 65].

This key is linked to the authorization certification which enables the connectorto be activated and used.



41/74

I. Appendix


AppendixI


42/74



43/74

This section provides information about the syntax used for the connector'sconfiguration wizard's XML file.

General structure

A wizard is made up of pages. Each pages can have input fields, labels and

descriptions. Each page defines a transition to the next page.

Wizard element

The root element must be wizard.

Possible sub-elements are:


Wizard file9


44/74


45/74

DescriptionOptionalElementDefines the controls on theYescontrol


46/74

page.Defines line breaks.YeslinebreakDefines a horizontal separator.Yesseparator

Note:

The first page of a connector's wizard must be named pgConnector.

Property element

A property is a basic value type such asstringor long. Possible attributes are:

DescriptionOptionalAttributeDefines the name of the prop-erty.

Noname

Used to ignore or not to ignorethe element.

Yesincluded

Used to specify scripted con-tent.

Yesscript

Example:

RetVal = 1

RetVal = ""

A property is used via the property full pathsyntax which references thecomplete path (without the root) of the property in the XML tree structure.


Example:

i ibl i { i ibl } l 1 / i ibl


47/74

{myPage.IsVisible} 1{DelimString}

Control element

Used to define a graphical control. Possible attributes are:

DescriptionOptionalAttribute

Defines the name of the prop-erty.

Noname

Defines the control type.

It must be unique for the page.

Notype

Used to ignore or not to ignorethe element.

Yesincluded

Used to specify scripted con-tent.

Yesscript

Possible sub-elements, regardless of the control type, are:

DescriptionTypeOptionalElementSpecifies whether ornot the control is vis-ible.

booleanYesvisible

Specifies whether or

not the control isgrayed out.

booleanYesenabled

Specifies whether ornot the control can beedited.

booleanYesreadonly

Specifies whether ornot the control re-quires a value.

booleanYesmandatory

Specifies the error

message if no value isprovided when themandatory attributeis present and is equalto 1.

stringYesmandatorymsg

Defines text above thecontrol.

stringYeslabel

If '1' or 'true', posi-tions the label to theleft.

booleanYeslabelleft



48/74

DescriptionTypeSub-elementControl typeSpecifies the maxim-um value

longmaxvalue


49/74

um value.Control labelstringcaptionlabelPath of the selectedfile.

stringvaluefileedit

Defines the editingtype:

n 1 = OPEN

n 2 = SAVE

n 4 = OPEN_DIR

n 8 = SAVE_DIR

n

16 = APPEND

longopenmode

Defines a file filter.

Example: XML files(*.xml)|*.xml|XMLS-chema files(*.xsd)|*.xsd|

stringfilters

Default extension touse.

Example: txt

stringdefext

Defines the id of thefile selection control.Several controls canuse the same id. Thisid is used to save the

path of the last selec-ted file.

stringserializationId

Value of the selecteditem.

stingvalueoptionbuttons

List of possible items(label=value) separ-ated by commas.

Example: ISO-8859-1=0,UTF-8=1,Shift-JIS=2

stringvalues

Specifies whether ornot the control has aframe.

booleanborder

Example:

$(GetValue[Server])


$(IDS_SERVER_LABEL)2500value


50/74

/

Bind attributeThe bindattribute is used to link a control to a configuration property of aconnector. Currently, only the value valueis supported by the SDK. When itis specified for a control named 'cs_myprop', the value of the control's element is sent to the connector as the value for the 'cs_myprop' configurationproperty (as the value of the 'myprop' property of the connector's

ConnectionSpecproperty).

Password managementManaging configuration properties such as passwords requires specific handlingin the wizards. If the property containing the password is 'cs_password', thename of the wizard control for this property must be 'clearcs_password'.

Example:$(GetValue[cs_password])1$(IDS_PASSWORD_LABEL)25001value

Linebreak and separator elements

These elements are used to format the wizard page. Possible attributes are:


DescriptionOptionalAttributeUsed to ignore or not to ignorethe element.

Yesincluded


51/74

the element.

Transition element

Every page must have a transition element. This element specifies what thenext page is. Possible attributes are:

DescriptionOptionalAttributeUsed to specify scripted con-tent.

Yesscript

Examples:

nextPage

if( $(GetValue[ShowAdvancedWiz]) = 1 ) thenRetVal = "pgAdvanced"elseRetVal = {trConnector}end if

Note:

The transition of the last page of a connector's wizard must be equal to the scriptedvalue {trConnector}.

Script attribute

Wizards support simple scripts written using Basic syntax. These scripts areevaluated when the wizard is executed.

The scriptattribute is available for all elements containing a value. It is usedto specify the value of the element as a scripted expression which is evaluatedwhen the value of the attribute is true.

Example:

if {Protocol.Value} = "ftp" or {Protocol.Value} = "http" then



52/74


53/74

Dump functionThis function is used to format a string for use in a script.The string is enclosedby quotation marks and quotation marks in the string are escaped This function


54/74

by quotation marks and quotation marks in the string are escaped.This functionis very useful in scripts that retrieve strings using the GetValuefunction orwith strings from an .strfile. The syntax is as follows:

$(Dump[string])

Example:

RetVal = $(Dump[$(GetValue[theValue])])

EspaceCommas functionThis function is used to escape commas in a string. The function can be usedwhen the string is a sub-element of a string that uses a comma as characterseparator (for example, the values element of the optionbuttonscontrol).Thesyntax is as follows:

$(EscapeCommas[string])

File functionThis function is used to retrieve the full path of a file. The syntax is as follows:

$(File[name,basedir])

The nameparameter specifies the file's name.The basedirparameter definesthe file's directory. The default directory is the wizard's directory.

Example:$(File[myfile.bmp])



55/74

This section provides information about the syntax used for the configurationfile.

The file is structured in the following manner:

configuration>


Configuration file10

Configuration element


56/74

The root element must be configuration. Possible sub-elements are:

DescriptionOptionalElementDefines one or more propertiesrequired by the connector'sJava code.

Yesproperty

Property element

Specifies a Java configuration property.

Possible attributes are:

DescriptionTypeOptionalAttributeDefines the name of

the property.

stringNoname

Specified the propertytype.

stringNotype

Specifies whether ornot the property needsto be taken into ac-count during export (-export option).

BooleanYesexport


DescriptionOptionalElementProperty definition.YesDefinitionDefinition of the export.YesexportDefinition of the correspondingJava class.

Yesclass

Definition element

Has the following sub-elements:


DescriptionTypeOptionalElementSpecifies the default

value that is usedwhen initializing the

stringYesdefault


57/74

when initializing thewizard.

Export element

Has the following sub-elements:

DescriptionTypeOptionalElementSpecifies the descrip-tion used when theproperty is exported.

Appears as a commentin the exported proper-ties file.

stringYesDescription

Class element

A Java class is implicitly associated with each property type.This element letsyou overload the implicit class of the property type.

In the example below, a Stringproperty type is declared and corresponds to aJavaBean property in thejava.net.URIclass.

java.net.URI

Property types

The following table lists the supported property types and their defaultJavaBean property type.

JavaBean TypeTypejava.lang.BooleanBooleanjava.lang.ByteBytejava.lang.ShortShort

java.lang.IntegerLong


JavaBean TypeTypejava.lang.LongLingIntjava.lang.FloatFloatjava.lang.DoubleDouble


58/74

java.lang.DoubleDoublejava.lang.StringString

java.lang.StringMemojava.util.DateDatejava.sql.TimeTimejava.sql.TimestampTimestampjava.lang.StringPasswordjava.io.FileFilejava.net.URLUrl

Please consult the JavaBeans documentation for the complete list of supportedJavaBean types.



59/74

This section provides information about the syntax used for the JVM

configuration file.The file is structured in the following manner:


JVM configuration file11

jvmConfiguration element

The root element must be jvmConfiguration


60/74

The root element must bejvmConfiguration.

Possible attributes are:

DescriptionTypeOptionalAttributeDefines a uniqueidentifier for the con-figuration.

stringNoid


DescriptionTypeOptionalElementDefines the paths ofthe classpath used bythe connector.

stringYesjarLocation

Defines the archivesused by the connector.

Yesjars

Used to include aclasspath from an ex-ternal file.

stringYesimport

Used to define JVMoptions.

YesjvmOptions

jarLocation element

The connector's classpath comprises one or more paths which reference thedifferent archives (.jar or .zip files) required for code execution. For eachconnector it is possible to define the paths to search for the archives. The pathvalue is either relative to the Connect-It installation lib directory or an absolutepath. The archives are searched in the order that the paths are declared.

Example:

./com.mycompany.myeisc:/myEIS/myEISPath

By default, if nojarLocationelement is specified, the path used is theConnect-It installation libdirectory.


Jars element



61/74

Possible sub elements are:

DescriptionTypeOptionalElementDefines an archiveentry for theclasspath.

stringYesjar

Jar elementPossible attributes are:

DescriptionDefaultTypeOptionalAttributeDefines a groupidentifier for thearchive.

stringNogroupId

Specifies if the

archive in questionis from one of theclasspath searchpaths or if the pathneeds to be providedby the user.

The value 'true' indic-ates that it is sup-plied by the installa-tion (search paths).In this case, the 'op-tional' attribute isignored.

truebooleanYesprovided


DescriptionDefaultTypeOptionalAttributeSpecifies if thearchive is optional.

The value 'false' indic-

falsebooleanYesoptional


62/74

ates that the archivemust be present inone of the classpathsearch paths, or inthe additionalclasspath defined inthe application('Java/ Configure theJVM' menu) or in the

connector (on thewizard's 'Configurethe JVM' page).Used to appendarchive version tothe archive.

The full name of thearchive becomesname-version.jar.

If this extension isnot found, a newsearch is done usingthe fullname name-version.zip.

stringYesversion

Indicates if archivemust be searched us-ing its name and

version.

n The value 'true'indicates that thesearch is on thename and the

version.

n The value 'false'indicates that thesearch is on the

name and theversion, then justthe name foreach path.

truebooleanYesversionNeeded

The value must reference the name of the archive to be added.

Sample classpath entry for thexercesImpl-2.6.2.jarlibrary that is providedwith the application:


xercesImpl


63/74

jvmOptions element

This element is used to define additional JVM options


DescriptionTypeOptionalElementDefines a JVM option.stringYesjvmOption

Example:

-Xmx125m-Dcom.sun.management.jmxremote

Import element

In addition to the connector's configuration, it is possible to provide additionalJVM configuration elements.Theses elements are declared in one or more fileswhich use the same syntax. Depending on where the import declaration ismade, the declarations can come before or after the current definitions. Thevalue must reference the relative path of the file to import.

Example:

../shared/jca-container-javaconf.xml



64/74



65/74

DescriptionDefault valueOptionalTypePropertyConnector namethat is displayed.

NostringName

Internal name ofthe connector

NostringInternalName


66/74

(unique).Name of the par-ent node that itbelongs to.

YesstringParentInternal-Name

HTMLHelpstring yes De-scription in htmlformat.

Activation keyNostringKeyIcon

Relative path tothe connector'sicon (.bmp)

NostringIconFile

Schedulers

The SDK doesnot provide sup-port for schedule

pointers. Thisvalue must be setto 0.

Sched.CanUsePoint-

er=0

trueYesbooleanSched.CanUsePoint-er

Cache

The SDK doesnot provide sup-port for the

metadata cache.This value mustbe set to 0.

Cache.Support-

Cache=0

trueYesbooleanCache.Support-Cache

Timezone

The SDK doesnot provide sup-

port for servertime differences.This value mustbe set to 0.

Tmz.HandleServer-

Delay=0

trueYesbooleanTmz.HandleServer-Delay

External

formats


DescriptionDefault valueOptionalTypePropertyThe SDK doesnot provide sup-port for extendedformats. This

trueYesbooleanExtFmt.Use


67/74

value must be setto 0.

ExtFmt.Use=0

Wizard

Relative path ofthe Wizard file.

YesstringWizard.File

Java

Specifies the con-

nector's Javaclass. Must be:

Java.Class=com.hp.ov.cit.container.RAContainer

NostringJava.Class

Relative path ofthe configurationfile.

YesstringJava.Configura-tion.File

Relative path ofthe JVM configur-ation file.

YesstringJava.JVMConfig-uration.File

This value shouldbe set to 1.Java.HasOp-tions=1

falseYesstringJava.HasOptions

Is a proxy serverconfigurationsupported?

falseYesBooleanJava.Support-Proxy

Does the recordof the proxy serv-er use the func-tion introducedby the class?

falseYesBooleanJava.PriorTo-Jdk15ProxyRegis-tration

Miscellaneous



68/74

Additional information


69/74

Multiple descriptionsA description file can contain several descriptions each of which correspondsto a CONNECTORDESCsection.Although it is recommended to write a singledescription file for each connector, including several descriptions in the samefile can be useful when defining connector categories or when managing differentversions of the same EIS.

Connector hierarchyThe ParentInternalNameproperty is used to specify the internal name ofthe parent node, or category, in the connector hierarchy. Categories are alsodefined in description files in a more simplified format:

{CONNECTORDESCInternalName=...ParentInternalName=...

Name=...HTMLHelp=...IconFile=...}

If no ParentInternalNameproperty is specified, the category (or the connector)will be located at the root of the hierarchy.

Connect-It has a certain number of predefined categories:

Internal nameCategoryApplication_connectorsApplication connectorsProtocol_connectorsProtocol connectorsERP_connectorsERP connectorsGatewaysInventory connectors



70/74


d3


71/74

JavaBeans

Supported typesA certain number of interfaces from the JCA specifications must be implementedas JavaBeans. The following interfaces are used by the SDK:

javax.resource.spi.ManagedConnectionFactory

javax.resource.spi.ResourceAdapterjavax.resource.cci.ConnectionSpecjavax.resource.spi.ActivationSpec

The following table lists the value types that are authorized for their properties:

java.lang.Booleanjava.lang.Stringjava.lang.Integerjava.lang.Doublejava.lang.Bytejava.lang.Shortjava.lang.Longjava.lang.Floatjava.lang.Character

The SDK extends this list to other frequently used types. The following types

are supported:


Java code13


72/74

To log messages to the Connect-It log, use theseorg.apache.commons.logging.Loginterface methods:

log.error(Object message);log.error(Object message, Throwable t);log.warn(Object message);log warn(Object message Throwable t);


73/74

log.warn(Object message, Throwable t);log.info(Object message);log.info(Object message, Throwable t);log.debug(Object message);log.debug(Object message, Throwable t);

Log4J support

The JCL framework is used to unify access to an implemented logging system:Log4J, JDK Logging, etc.

By default, Connect-It uses a configuration of the Log4J library. All messageslogged by the Log4J layer, whether called directly or via the JCL API, will betaken into account by Connect-It.

JDK logging supportConnect-It adds support for the logging framework supplied by the JDK thanksto a static configuration. The default static configuration is described by the\lib\logging.propertiesfile.

When the connector is instantiated, the logging level of the JDK's root loggeris modified to make it correspond to the one configured for the Connect-Itapplication. All log events, obtained via a direct call to the JDK loggingframework, are redirected to the application.

Internationalization

The SDK uses Java's standard internationalization mechanism. To implementthis mechanism with your code, you will need to create one or more propertiesfiles that will contain the strings required for internationalization.

Examplecom/mycompany/myeis/i18n/mymessages.propertiesfile

connection.error = Connection error.execution.failed = Execution failed.

com/mycompany/myeis/i18n/mymessages_fr.propertiesfile


connection.error = Erreur de connexion.execution.failed = Echec de l'excution.

com/mycompany/myeis/MyEISClass.javafile

package com.mycompany.myeis;

import ja a til Reso rceB ndle


74/74

import java.util.ResourceBundle;import org.apache.commons.logging.Log;import org.apache.commons.logging.LogFactory;

public class MyEISClass{private static final ResourceBundle bundle = ResourceBundle.getBundle("com.mycompany.myeis.i18n.mymessages");private static final Log log = LogFactory.getLog(MyEISClass.class);

public void execute(){try{...}catch(Exception e){log.error(bundle.getString("execution.failed"), e);

}}}


Hp Man CIT9.30 SDK PDF

Documents

Transcript of Hp Man CIT9.30 SDK PDF