TIBCO ActiveMatrix

(1)

TIBCO ActiveMatrix ^® Service Grid Java Component Development

Software Release 3.2.0

August 2012

(2)

(3)

Important Information

SOME TIBCO SOFTWARE EMBEDS OR BUNDLES OTHER TIBCO SOFTWARE. USE OF SUCH EMBEDDED OR BUNDLED TIBCO SOFTWARE IS SOLELY TO ENABLE THE FUNCTIONALITY (OR PROVIDE LIMITED ADD-ON FUNCTIONALITY) OF THE LICENSED TIBCO SOFTWARE. THE EMBEDDED OR BUNDLED SOFTWARE IS NOT LICENSED TO BE USED OR ACCESSED BY ANY OTHER TIBCO SOFTWARE OR FOR ANY OTHER PURPOSE.

USE OF TIBCO SOFTWARE AND THIS DOCUMENT IS SUBJECT TO THE TERMS AND CONDITIONS OF A LICENSE AGREEMENT FOUND IN EITHER A SEPARATELY EXECUTED SOFTWARE LICENSE AGREEMENT, OR, IF THERE IS NO SUCH SEPARATE AGREEMENT, THE CLICKWRAP END USER LICENSE AGREEMENT WHICH IS DISPLAYED DURING DOWNLOAD OR INSTALLATION OF THE SOFTWARE (AND WHICH IS DUPLICATED IN THE LICENSE FILE) OR IF THERE IS NO SUCH SOFTWARE LICENSE AGREEMENT OR CLICKWRAP END USER LICENSE AGREEMENT, THE LICENSE(S) LOCATED IN THE “LICENSE” FILE(S) OF THE SOFTWARE. USE OF THIS DOCUMENT IS SUBJECT TO THOSE TERMS AND CONDITIONS, AND YOUR USE HEREOF SHALL CONSTITUTE ACCEPTANCE OF AND AN AGREEMENT TO BE BOUND BY THE SAME.

This document contains confidential information that is subject to U.S. and international copyright laws and treaties.

No part of this document may be reproduced in any form without the written authorization of TIBCO Software Inc.

TIBCO, The Power of Now, TIBCO ActiveMatrix, and TIBCO Enterprise Message Service are either registered trademarks or trademarks of TIBCO Software Inc. in the United States and/or other countries.

EJB, Java EE, J2EE, and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.

All other product and company names and marks mentioned in this document are the property of their respective owners and are mentioned for identification purposes only.

THIS SOFTWARE MAY BE AVAILABLE ON MULTIPLE OPERATING SYSTEMS. HOWEVER, NOT ALL OPERATING SYSTEM PLATFORMS FOR A SPECIFIC SOFTWARE VERSION ARE RELEASED AT THE SAME TIME. SEE THE README FILE FOR THE AVAILABILITY OF THIS SOFTWARE VERSION ON A SPECIFIC OPERATING SYSTEM PLATFORM.

THIS DOCUMENT IS PROVIDED “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESS OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE PERIODICALLYADDED TO THE INFORMATION HEREIN; THESE CHANGES WILL BE INCORPORATED IN NEW EDITIONS OF THIS DOCUMENT. TIBCO SOFTWARE INC. MAY MAKE IMPROVEMENTS AND/OR CHANGES IN THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THIS DOCUMENT AT ANY TIME.

THE CONTENTS OF THIS DOCUMENT MAY BE MODIFIED AND/OR QUALIFIED, DIRECTLY OR INDIRECTLY,

(4)

(5)

Preface...7

Changes from the Previous Release of this Guide...8

TIBCO Product Documentation...9

Chapter 1 Java Components...15

Creating a Java Component...16

Configuring a Java Component's Implementation...17

Updating a Java Component...18

Configuring a Java Component's Custom Feature...19

Upgrading a Java Component...20

Component Feature Dependencies...21

Java Component Reference...22

Chapter 2 Java Component Implementations...25

Data Binding...27

Generating XML Data Binding Classes...27

Data Binding Classes for Abstract and Concrete WSDL Files...28

XML Data Binding Reference...28

Opening a Java Component Implementation...31

Generating a Java Component Implementation...32

Generate Java Component Implementation Reference...34

Regenerating a Java Component Implementation...37

Upgrading a Java Component Implementation...39

Life Cycle Events...40

Component Context...41

Accessing a Property...42

TOC | 5

(6)

Error Handling...55

SOAPException Reference...58

Context Parameters...60

Accessing a Context Parameter...62

Endpoint References...65

Retrieving an Endpoint Reference...65

Creating an Endpoint Reference...65

Chapter 3 Custom Features...67

Bundles and Plug-in Projects...69

Configuring Dependencies on External Java Classes...70

Versions...72

Appendix A Java API Reference...73

Appendix B Converting Migrated Java Component Implementations.75

Create Abstract Class...76

Edit Manifest...79

Regenerate Component Implementation...80

Remove 2.x Data Binding JAR Files...81

Correct Custom Feature File...82

Appendix C Default XML to Java Mapping...83

TIBCO ActiveMatrix Service Grid Java Component Development 6 | TOC

(7)

Preface

TIBCO ActiveMatrix^®Service Grid is a scalable and extensible platform for developing, deploying, and managing applications that conform to a service-oriented architecture.

(8)

Changes from the Previous Release of this Guide

This section itemizes the major changes from the previous release of this guide.

• Added Component Feature Dependencies on page 21.

• Added Data Binding on page 27 and updated Generating a Java Component Implementation on page 32 and Generate Java Component Implementation Reference on page 34 to address new data binding options.

• Updated Configuring Dependencies on External Java Classes on page 70.

• Added Bundles and Plug-in Projects on page 69 and Versions on page 72.

• Added Creating an Endpoint Reference on page 65.

TIBCO ActiveMatrix Service Grid Java Component Development 8 | Preface

(9)

TIBCO Product Documentation

This section lists documentation resources you may find useful.

The following documents form the TIBCO ActiveMatrix^®Service Grid documentation set:

• Concepts: Read this manual before reading any other manual in the documentation set. This manual describes terminology and concepts of the TIBCO ActiveMatrix platform. The other manuals in the documentation set assume you are familiar with the information in this manual.

• Development Tutorials: Read this manual for a step-by-step introduction to the process of creating, packaging, and running composites in TIBCO Business Studio.

• Composite Development: Read this manual to learn how to develop and package composites.

• Java Component Development: Read this manual to learn how to configure and implement Java components.

• Mediation Component Development: Read this manual to learn how to configure and implement Mediation components.

• Mediation API Reference: Read this manual to learn how to develop custom Mediation tasks.

• Spring Component Development: Read this manual to learn how to configure and implement Spring components.

• WebApp Component Development: Read this manual to learn how to configure and implement Web Application components.

• Administration Tutorials: Read this manual for a step-by-step introduction to the process of creating and starting the TIBCO ActiveMatrix runtime, starting TIBCO ActiveMatrix servers, and deploying applications to the runtime.

• Administration: Read this manual to learn how to manage the runtime and deploy and manage applications.

• Installation and Configuration: Read this manual to learn how to install TIBCO ActiveMatrix Service Grid software and create and upgrade runtime objects.

• Release Notes: Read this manual for a list of new and changed features, steps for migrating from a previous release, and lists of known issues and closed issues for the release.

The documentation for the following features is installed separately:

• TIBCO ActiveMatrix Implementation Type for C++

• TIBCO ActiveMatrix Binding Type for EJB

• TIBCO ActiveMatrix Binding Type for Adapters

• TIBCO ActiveMatrix Implementation Type for Adapters

• TIBCO ActiveMatrix Implementation Type for Microsoft CLR

Preface | 9

(10)

Typographical Conventions

Table 1: General Typographical Conventions Use

Convention

TIBCO products are installed into an installation environment. A product installed into an installation environment does not access components in other installation environments.

TIBCO_HOME ENV_NAME

Incompatible products and multiple instances of the same product must be installed into different installation environments. An installation environment consists of the following properties:

• Name - Identifies the installation environment. The name is appended to the name of Windows services created by the installer and is a component of the path to the product shortcut in the Windows Start > All Programs menu. This name is referenced in documentation as ENV_NAME.

• Path - The folder into which the product is installed. This folder is referenced in documentation as TIBCO_HOME.

The folder that stores configuration data generated by TIBCO products. Configuration data can include sample scripts, session data, configured binaries, logs, and so on. This folder is referenced in documentation as CONFIG_HOME.

CONFIG_HOME

Code font identifies commands, code examples, filenames, pathnames, and output displayed in a command window. For example:

code font

• Use ^MyCommand to start the foo process.

• Code example:

public class HelloWorldImpl extends AbstractHelloWorldImpl { ...

public HelloResponseDocument sayHello(HelloRequestDocument firstName) {

...

System.out.println("--> Generating Java Hello Component Response...");

String name =

firstName.getHelloRequest()==null||firstName.getHelloRequest().

equals("")?"Friend":firstName.getHelloRequest();

HelloResponseDocument resp =

HelloResponseDocument.Factory.newInstance();

resp.setHelloResponse("Hi " + name + "! " + "This is the Java component.\n");

System.out.println("--> Java Hello Component Response: \n\t\t"

+

resp.getHelloResponse());

...

} }

• CONFIG_HOME^/admin/enterpriseName/samples/remote_props.properties

Preface | 11

(12)

Use Convention

Bold code font is used in the following ways:

bold code font

• In procedures, to indicate what a user types. For example: ^{Type admin}.

• In large code samples, to indicate the parts of the sample that are of particular interest.

• In command syntax, to indicate the default parameter for a command. For example, if no parameter is specified, MyCommand is enabled:

MyCommand [enable | disable]

Italic font is used in the following ways:

italic font

• To indicate a document title. For example: See TIBCO BusinessWorks Concepts.

• To define new terms. For example: A keystore is a database of keys and certificates.

• To indicate a variable in a command or code syntax that you must replace. For example:

MyCommandpathname.

Key name separated by a plus sign indicate keys pressed simultaneously. For example:

Ctrl+C.

Key names separated by a comma and space indicate keys pressed one after the other.

For example: Esc, Ctrl+Q.

Key

combinations

The note icon indicates information that is of special interest or importance, for example, an additional action required only in certain circumstances.

The tip icon indicates an idea that could be useful, for example, a way to apply the information provided in the current section to achieve a specific result.

The warning icon indicates the potential for a damaging situation, for example, data loss or corruption if certain steps are taken or not taken.

Table 2: Syntax Typographical Conventions Use

Convention

An optional item in command syntax.

For example:

[ ]

MyCommand [optional_parameter] required_parameter

A logical ’OR’ that separates multiple items of which only one may be chosen.

For example, you can select only one of the following parameters:

|

MyCommand param1 | ^param2 | ^param3

A logical group of items in a command. Other syntax notations may appear within each logical group.

For example, the following command requires two parameters, which can be either the pair param1 and param2, or the pair param3 and param4.

{ }

MyCommand {param1 param2} | {param3 param4}

In the next example, the command requires two parameters. The first parameter can be either param1 or param2 and the second can be either param3 or param4:

MyCommand {param1 | param2} {param3 | param4}

(13)

Use Convention

In the next example, the command can accept either two or three parameters. The first parameter must be param1. You can optionally include ^param2 as the second parameter.

And the last parameter is either ^param3 or ^param4.

MyCommand param1 [^param2] {^param3 | ^param4}

Preface | 13

(14)

Connecting with TIBCO Resources

How to Join TIBCOmmunity

TIBCOmmunity is an online destination for TIBCO customers, partners, and resident experts. It is a place to share and access the collective experience of the TIBCO community. TIBCOmmunity offers forums, blogs, and access to a variety of resources. To register, go to http://www.tibcommunity.com.

How to Access TIBCO Documentation

After you join TIBCOmmunity, you can access the documentation here: http://docs.tibco.com.

How to Contact TIBCO Support

For comments or problems with this manual or the software it addresses, contact TIBCO Support as follows:

• For an overview of TIBCO Support, and information about getting started with TIBCO Support, visit this site:

http://www.tibco.com/services/support

• If you already have a valid maintenance or support contract, visit this site:

https://support.tibco.com

Entry to this site requires a username and password. If you do not have a username, you can request one.

(15)

Chapter

1

Java Components

Java components integrate Java classes into the TIBCO ActiveMatrix platform. The integration conforms to SCA-J specifications. Java components support service implementation using the flexibility and power of a general purpose programming language.

TIBCO Business Studio facilitates Java component implementation by providing a rich set of automatic code generation and synchronization features. TIBCO Business Studio supports both WSDL-first and code-first development.

You can develop Java components and generate classes that conform to the WSDL interface specification of the component's services and references. When you add a service, reference, or property to a Java component and regenerate the implementation, TIBCO Business Studio adds fields and methods that represent the service, reference, or property to the component's implementation class.

You can also configure an existing Java class as the implementation of a Java component and update component properties to match the implementation.

For information on Java components, see Java Component Development.

Topics

• Creating a Java Component

• Configuring a Java Component's Implementation

• Updating a Java Component

• Configuring a Java Component's Custom Feature

• Upgrading a Java Component

• Component Feature Dependencies

• Java Component Reference

(16)

Creating a Java Component

About this task

You can create a Java component by starting with a WSDL file and generating the component implementation, or by creating the component and configuring it with an existing implementation.

Procedure

Choose an option and follow the relevant procedure.

Description Option

Wizard 1. Create an SOA project selecting the SOA Project from WSDL project type.

2. In the Component Details page of the wizard, specify Java for the component implementation type.

3. Specify code generation details as described in Generate Java Component Implementation Reference on page 34.

Manual 1. Create an SOA project of any type.

2. Open the composite created in the project.

3. Do one of the following:

– Click the Java icon in the Palette and click the canvas.

– Click the canvas and click the Java icon in the pop-up toolbar.

4. Generate the Java implementation as described in Generating a Java Component Implementation on page 32 or configure an existing implementation as described in Configuring a Java

Component's Implementation on page 17.

Command-Line 1. Create a command-line build file and specify an sds.createComponent task. Use <param name="..." value="..."/> subelements to specify details about the containing the plug-in that contains the component implementation. For example:

<sds.createComponent projectName="NewSoaProject" compositeName="MyComposite"

componentName="MyJavaComponent"

implementationLoc="/MyJavaProject/src/com/example/impl/MyJavaComponentImpl.java">

<param name="feature.file.path"

value="/NewSoaProject/Deployment Artifacts/MyCustomFeature.customfeature"/>

</sds.createComponent>

2. Run the command-line with the build file.

A Java component is added to the composite and its implementation is configured.

TIBCO ActiveMatrix Service Grid Java Component Development 16 | Java Components

(17)

Configuring a Java Component's Implementation

About this task

When you generate a Java component implementation or create an SOA project from a Java implementation, the component's Implementation field is configured automatically.

You can also manually configure an existing Java class in the workspace as the implementation of a Java component. The class must be contained within a Java plug-in project. If you configure a class that is not contained within a plug-in project, TIBCO Business Studio will convert the project to a plug-in project when you configure the implementation.

The Java class must conform to 3.x format as described in the appendix Converting Migrated Java Component Implementations on page 75 in order to be able to regenerate the class after adding references, services, or properties. If your class does not conform to 3.x format, follow the procedures in the appendix to migrate the implementation class to 3.x format.

Procedure

1. Click the component.

2. In the Properties view, click the Implementation tab.

3. Click the Browse... button at the right of the Class field.

The Select Implementation Class displays.

4. In the Select Entries field, type a partial class name.

The classes that match the name display in the Matching types list.

5. Click a class and click OK.

The Class and Location fields are filled in. An error badge is added to the component. To resolve the error, configure the component's custom feature and update the component.

Related Topics

Custom Features on page 67

Java Components | 17

(18)

Updating a Java Component

About this task

You typically update a component after you have configured its implementation.

Procedure

Procedure Control

Canvas 1. Right-click the component and select Refresh from Implementation.

Canvas 1. Right-click a component and select Quick Fixes > Update Component from Implementation.

Problems View 1. In the Problems view, right-click an error of the form The component

"ComponentName" is out of sync with its implementation and select Quick Fix.

2. In the Quick Fix dialog select Update Component from Implementation.

3. Click Finish.

All the changes made to the component since the implementation was generated are discarded and the component is refreshed from the implementation.

(19)

Configuring a Java Component's Custom Feature

About this task

When you generate a Java component implementation or create an SOA project from a Java implementation, the component's custom feature field is automatically created and configured. If you manually configure the component's implementation, you must manually create and configure the custom feature. If the component implementation uses a library, add the custom feature containing the library in the Properties view.

Procedure

1. Choose an initial control and follow the relevant procedure.

Procedure Initial Control

Properties View 1. Click the component.

2. In the Properties view, click the Implementation tab.

3.

Click the button to the right of the Features table.

Quick Fix 1. Right-click the component and select Quick Fixes > Select Custom Feature

The Select a Feature dialog displays.

2. In the Select an item to open field, type a partial feature name.

The feature that matches the name displays in the Matching items list.

3. Click a feature and click OK.

The feature is added to the Features list.

Related Topics

Custom Features on page 67

(20)

Upgrading a Java Component

About this task

After you modify a Java component and its implementation you should update the relevant plug-in, feature, and component versions. Observe the following guidelines for updating version components according to the type of modification you make:

• Major - Deleting a property, service, reference, or component and any code changes that are not backward compatible.

• Minor - Adding a property, service, reference or component and any changes that are backward compatible.

• Service - Modifying a property, service, reference, or components that is backward compatible. For example, if you make a minor change to the implementation.

Procedure

1. Open the plug-in manifest of the plug-in containing the component implementation.

a) In the Overview tab, increment the appropriate version component of the plug-in. For example, if you add a property, change 1.0.0.qualifier to 1.1.0.qualifier.

b) In the Runtime tab, increment the appropriate version component of the exported package. For example, if you add a property, change 1.0.0.qualifier to 1.1.0.qualifier.

c) Save the manifest.

2. Open the custom feature containing the plug-in.

a) In the Overview tab, increment the appropriate version component of the feature. For example, if you add a property, change 1.0.0.qualifier to 1.1.0.qualifier.

b) In the Plug-ins tab, increment the appropriate version component of the included plug-in. For example, if you add a property, change 1.0.0.qualifier to 1.1.0.qualifier.

c) Save the feature.

3. Click the modified component.

a) In the General tab, increment the appropriate version component of the component. For example, if you add a property, change 1.0.0.qualifier to 1.1.0.qualifier.

b) In the Implementation tab, if the Compute Component Dependencies and Feature Dependencies checkboxes are unchecked, update the version ranges for the component implementation bundle or package and feature as appropriate. For example, if you add a property, change the version range from [1.0.0, 2.0.0) to [1.1.0, 2.0.0). If the checkboxes are checked, TIBCO Business Studio automatically updates the applicable version ranges.

4. Save the composite.

5. Create a DAA containing the upgraded composite and feature.

(21)

Component Feature Dependencies

When a component implementation is dependent on a shared library, the feature containing the dependency must be specified in the component's Feature Dependencies table. By default, a component is configured to depend on the custom features containing:

• The component implementation

• External libraries reference by the component implementation

In both cases, the default version range is set to "[1.0.0.qualifier,1.0.0.qualifier]".

If the qualifier component of a version is set to "qualifier" when you create a DAA, TIBCO Business Studio replaces "qualifier" with a generated qualifier that defaults to a timestamp.. The effect is that the application requires that the version of the features installed on a node be a perfect match to a version that includes a timestamp.

External Library Dependencies

It is not possible to know the value of the version's qualifier component for the feature containing an external library when you package the composite. Therefore, if you are using an external library, you should "relax"

the version range of the feature containing the library. For example, change the range from

"[1.0.0.qualifier,1.0.0.qualifier]" to "[1.0.0,2.0.0)" as shown in Figure 1: Relaxed Feature Dependency on page 21.

Figure 1: Relaxed Feature Dependency

(22)

Java Component Reference

Description Field

The fully-qualified name of the class that implements the component.

Class

The location of the class in the workspace.

Location

Configures the value returned by the call

Thread.currentThread().getContextClassLoader() inside a Java implementation class (once it is instantiated):

Thread Context Class Loader Type

• component - The class loader of the component configured through the component requirements

• bundle - The class loader of the bundle (that is, plug-in) that contains the Java implementation class.

• none - A null thread context class loader.

Indicate whether to TIBCO Business Studio should compute the component bundle dependencies. When a component is deployed on a node, ActiveMatrix generates a Compute

Component

Dependencies component bundle. When checked, the component implementation bundles required by the component bundle are computed and identified when you package the composite. When unchecked, the Implementation Dependency and Compute Feature Dependencies fields display and you can manually specify the dependencies.

Default:

• New projects - checked.

• Legacy projects - unchecked.

The type of the dependency of the component bundle on the component implementation.

Implementation Dependency

• Require Bundle - The bundle containing the component implementation is declared as a required bundle. When selected, the Bundle Name field appears.

• Import Package - The package exported by the component implementation is declared as an imported package. When selected, the Import Package field displays.

Default:

• New projects - Require Bundle.

• Legacy projects - Import Package.

The symbolic name of the bundle containing the component implementation.

Default: The bundle in which the component implementation class is present.

Bundle Name

The name of the package containing the component implementation.

Default: The package in which the component implementation class is present.

Package Name

The versions of the bundle or package that satisfy the component bundle's dependency.

When specifying a range for a bundle, you can require an exact match to a version that includes a build qualifier. In contrast, the range for a package is inexact.

Default:

Version Range

• Bundle - [1.0.0.qualifier,1.0.0.qualifier].

(23)

• Package - [1.0.0, 2.0.0).

Indicate whether to compute the features on which the component bundle depends.

When unchecked the Feature Dependencies table displays.

Default:

Compute Feature Dependencies

• New projects - checked.

• Legacy projects - unchecked.

A link that when clicked displays a dialog containing a list of the features on which the component bundle depends.

Preview

Features Dependencies

The features on which the component bundle depends.

Description Column

The ID of the feature.

Feature ID

The range of feature versions.

Version Range

By default the table contains the automatically generated feature containing the component implementation bundle.

sds.CreateComponent Command-Line Task Description

Element or Parameter

The workspace relative path to the implementation class.

implementationLoc

The ID of the feature.

feature.id

The workspace relative path to the feature file.

feature.file.path

Indicate whether to create a new feature.

create.new.feature

Indicate whether to use an existing feature.

use.existing.feature

The feature version.

feature.version

Related Topics

Bundles and Plug-in Projects on page 69

(24)

(25)

Chapter

2

Java Component Implementations

A Java component implementation consists of the abstract and concrete classes that represent the component. The abstract class defines service method signatures, reference fields and accessor methods, and property fields and accessor methods. The concrete class contains the implementations of the service methods. Java component implementations are stored in Java plug-in projects.

Declaring Dependencies on javax.xml.* Packages

Normally if you import packages and do not add them to the manifest TIBCO Business Studio displays an error.

However, If you import any of the javax.xml.* packages and do not declare the import in the manifest, TIBCO Business Studio does not display an error because TIBCO Business Studio resolves those packages from the configured JRE. If you then deploy the application without the declaration in the manifest, the application will not run. Hence you must ensure that you import ^javax.xml packages in the manifest file. For example, if you imported the following classes:

import javax.xml.XMLConstants;

import javax.xml.transform.TransformerFactory;

The corresponding import packages in the manifest should be:

Each subpackage of javax.xml may have a different version:

(26)

Topics

• Data Binding

• Opening a Java Component Implementation

• Generating a Java Component Implementation

• Generate Java Component Implementation Reference

• Regenerating a Java Component Implementation

• Upgrading a Java Component Implementation

• Life Cycle Events

• Component Context

• Accessing a Property

• Accessing a Resource

• Invoking an HTTP Request

• Invoking a Reference Operation

• Error Handling

• Context Parameters

• Endpoint References

TIBCO ActiveMatrix Service Grid Java Component Development 26 | Java Component Implementations

(27)

Data Binding

Data binding is the process of converting objects described in an XML document to Java objects and vice versa. You can generate data binding classes directly from a WSDL or schema document or while generating a Java or Spring component implementation. TIBCO Business Studio supports two data binding technologies:

JAXB and XMLBeans. The default mapping of WSDL and XSD schema elements to Java programming language elements is described in Default XML to Java Mapping on page 83.

Data Binding Configuration Files

You can change the mapping of XML elements to Java objects by specifying mapping constraints in a data binding configuration file. Each data binding technology has its own configuration file format: XMLBeans XSDCONFIG or JAXB XJB. See the XMLBeans and JAXB specifications for the formats of their configuration files.

For example, the following XMLBeans configuration file maps the target namespace

http://ns.tibco.com/Hello/ to the package com.sample.othername.hello and specifies suffixes, prefixes, and name replacements for generated classes.

<xb:config xmlns:xb="http://xml.apache.org/xmlbeans/2004/02/xbean/config"

xmlns:ct="http://ns.tibco.com/Hello/">

<xb:namespace uri="http://ns.tibco.com/Hello/ http://someurihere.com">

<xb:package>com.sample.othername.hello</xb:package>

</xb:namespace>

<!--

The ##any value is used to indicate "all URIs".

The <prefix> tag is used to prepend to top-level Java type names generated in the specified namespace.

The <suffix> tag is used to append to top-level Java types names generated in the specified namespace.

The <prefix> and <suffix> are not used for inner Java types.

-->

<xb:namespace uri="##any">

<xb:prefix>Xml</xb:prefix>

<xb:suffix>BeanClass</xb:suffix>

</xb:namespace>

<xb:qname name="ct:HelloResponse" javaname="TheHelloResponse" />

</xb:config>

Related Topics

Generating a Java Component Implementation on page 32

Generating XML Data Binding Classes

Java Component Implementations | 27

(28)

4. In the Project Explorer, right-click a WSDL or schema document and select Generate XML Data Bindings.

The XML Data Binding Classes dialog displays.

5. Configure the XML data binding type and Beans and interface JAR file properties as described in XML Data Binding Reference on page 28.

A JAR file containing the XML data binding classes for each WSDL and schema document is created in the specified location unless you click the Use this JAR for All Data Bindings link.

Data Binding Classes for Abstract and Concrete WSDL Files

Using an abstract WSDL and its generated concrete WSDL in services and references of the same component requires special consideration if the WSDL contains an embedded schema. When a concrete WSDL file is generated from an abstract WSDL file that has an embedded schema, the resulting concrete WSDL file will also contain the same embedded schema. When you generate data binding classes for both WSDL files, the code generator generates duplicate classes for the embedded schema. The impact of this is twofold:

• Generating the data binding classes for the abstract and concrete WSDL files into a single JAR is not supported.

• When you generate the data binding classes for the two WSDL files into different bean JARs, both JARs will contain the same classes.

For correct operation, you must manually remove one of the resulting bean JARs from the bundle containing the bean JARs as follows:

1. Open the component implementation bundle's manifest in the Manifest Editor.

2. Click the Runtime tab, and delete one of the JARs containing the duplicate bean classes from the Classpath area.

3. Save the manifest.

To avoid having to manually edit the manifest, the recommended method for using abstract and concrete WSDL files in the same composite is to use only abstract WSDL files for the component services and references and use the concrete WSDL only for the corresponding promoted references as follows:

1. Delete the wire between component references and promoted references.

2. Configure the component reference with the abstract WSDL.

3. Configure the promoted reference with the concrete WSDL.

4. Wire the component reference to the promoted reference using the Wire tool in the Palette.

XML Data Binding Reference

The type of the data binding being generated: XMLBeans or JAXB.

If a JAR file already exists for the contract selected in the Contracts list, and you choose a binding type different than the one that exists in the JAR file or the contract has Type

changed since the JAR file was generated, the Overwrite Existing JAR checkbox will be checked.

Default: XMLBeans.

Generating implementations for two or more components in the same Java plug-in project using different binding types is not supported.

A list of WSDL and schema files for which XML data binding classes will be generated.

Contracts

The type of JAR file being generated: Beans or Interface.

JAR Type

The path to the source file containing the selected contract.

Source File

(29)

The path to the generated JAR file.

Default: When generating a component implementation:

JAR File

• Beans - projectName^/libs/contractFileName^.wsdl.jar

• Interface - projectName^/libs/contractFileName.wsdl_interface.jar

where contractFileName is the name of the file containing the contract selected in the Contracts list and projectName is the name of the project containing the component implementation.

When generating from a contract file:

• Beans - projectName.libs/libs/contractFileName^.wsdl.jar

• Interface - projectName.libs/libs/contractFileName.wsdl_interface.jar

where contractFileName is the name of the file containing the contract selected in the Contracts list and projectName is the name of the project containing the contract file.

Indicate that all data binding classes should be generated into the JAR file specified in the JAR File field. You must generate all data binding classes into a single JAR file whenever there are cyclical references between schema files.

Use this JAR for All Data Bindings

Invokes a dialog where you can set the folder to contain generated JAR files:

Set JAR Folder

• All Generated JARs - All JAR files will be generated in the same folder as the destination of the currently selected JAR.

• New Generated JARs - Only newly generated JAR files will be generated in the same folder as the destination of the currently selected JAR file.

Setting the JAR folder affects only the JAR files generated by the wizard. It has no effect outside the wizard nor on subsequent wizard runs.

Default: All Generated JARs.

The status of the JAR file containing the classes generated for the selected contract:

JAR Status

• JAR is non-existent and will be generated. - The JAR file does not exist.

• Different binding type. JAR must be overwritten. - The value of the Type field is different than the type of the data binding classes in the JAR file.

• JAR exists and will be overwritten. - The JAR file exists and the Overwrite Existing JAR checkbox is checked.

• JAR exists and will be preserved. - The JAR file exists and the Overwrite Existing JAR checkbox is unchecked.

• JAR is outdated and will be overwritten. - The selected contract has changed since the JAR file was generated and the Overwrite Existing JAR checkbox is checked, so the JAR file will be generated.

• JAR is outdated and will be preserved. - The selected contract has changed since the JAR file was generated and the Overwrite Existing JAR checkbox is unchecked,

(30)

this is not the recommended approach for data binding library sharing. Instead you should generate data binding JAR files into a separate plug-in project.

Default: Unchecked.

Indicate that the specified data binding configuration file should be used when generating JAR files. When you check the checkbox, the text field is enabled.

Default: Unchecked.

Use Configuration File

(31)

Opening a Java Component Implementation

Procedure

Choose an initial control and follow the relevant procedure.

Double-click the component.

Canvas

Properties View 1. Click the Implementation tab.

2. Click the Class field label.

Right-click the implementation file and select Open With > Java Editor.

Project Explorer

Right-click the component and select Open Implementation.

Canvas

The implementation file opens in the Java editor.

(32)

Generating a Java Component Implementation

Procedure

Properties View 1. In the Validation Report area on the General tab of the component's Property View, click the fix... link.

2. Select Generate Java Implementation.

Canvas 1. Right-click the component and select Quick Fixes > Generate Java Implementation .

Canvas 1. Right-click the component and select Generate Java Implementation.

Problems View 1. In the Problems view, right-click an error of the form ^Component

"ComponentName" is not configured and select Quick Fixes.

2. In the Quick Fix dialog, click Generate Java Implementation.

The Generate Java Implementation dialog displays.

2. Configure the project, package, and class details in the Implementation Classes on page 34 screen.

3. If the component has a service or reference, choose a data binding option and follow the appropriate procedure:

Procedure Data Binding

Option

A JAR containing XMLBeans data binding classes with the default options is generated.

Accept Defaults

Configure 1. Click Next.

2. Configure the data binding type and Beans and interface JAR properties as described in XML Data Binding Reference on page 28.

The following objects are generated:

• A Java plug-in project containing abstract and concrete implementation classes. If the component has a service or reference, interface and data binding classes are also generated.

• A custom feature file that references the Java plug-in in the Deployment Artifacts special folder in the SOA project. The component is configured to depend on the generated custom feature. If the component implementation depends on a data binding library plug-in, the component is configured to depend on the custom feature containing the data binding library.

• Objects that map to the following component elements:

– Service - An interface. If the port type is named PortType, the interface is named PortType. The clause

implementsPortType is added to the abstract class.

– Reference - Field and accessor methods are added to the abstract class.

– Property - Field and accessor methods are added to the abstract class.

Related Topics

Default XML to Java Mapping on page 83

(33)

Generate Java Component Implementation Reference on page 34 Data Binding on page 27

(34)

Generate Java Component Implementation Reference

When you generate a Java implementation you specify the project location, package, and names of the implementation classes and the type of the XML data binding classes and location of the JAR file containing the classes.

Implementation Classes Description Field

The name of the plug-in project to contain the implementation.

Default: com.sample.soaprojectname. Project

The name of the source folder in the plug-in project.

Default: ^src. Source Folder

The name of the package of the implementation class.

Default: com.sample.soaprojectname. Package

The name of the implementation class.

Default: ComponentName, where ComponentName is the name of the component.

Class

Indicate whether to overwrite the implementation class if it already exists.

Default: Unchecked.

Overwrite Concrete Class

Indicate whether to generate the superclass of the implementation class in the same package as the implementation class and name the class AbstractComponentName. When unchecked, the Superclass Package and Superclass fields are enabled.

Default: Checked.

Use Default Location for Superclass

The name of the package of the superclass of the implementation class.

Default: com.sample.soaprojectname. Superclass

Package

The name of the superclass of the implementation class.

Default: ^AbstractComponentName. Superclass

XML Data Binding Classes

If the component does not have any services or references, this screen does not display.

The type of the data binding being generated: XMLBeans or JAXB.

If a JAR file already exists for the contract selected in the Contracts list, and you choose a binding type different than the one that exists in the JAR file or the contract has Type

changed since the JAR file was generated, the Overwrite Existing JAR checkbox will be checked.

Default: XMLBeans.

(35)

Generating implementations for two or more components in the same Java plug-in project using different binding types is not supported.

A list of WSDL and schema files for which XML data binding classes will be generated.

Contracts

The type of JAR file being generated: Beans or Interface.

JAR Type

The path to the source file containing the selected contract.

Source File

The path to the generated JAR file.

Default: When generating a component implementation:

JAR File

• Beans - projectName^/libs/contractFileName^.wsdl.jar

• Interface - projectName/libs/contractFileName.wsdl_interface.jar

where contractFileName is the name of the file containing the contract selected in the Contracts list and projectName is the name of the project containing the component implementation.

When generating from a contract file:

• Beans - projectName.libs/libs/contractFileName^.wsdl.jar

• Interface - projectName.libs/libs/contractFileName.wsdl_interface.jar

where contractFileName is the name of the file containing the contract selected in the Contracts list and projectName is the name of the project containing the contract file.

Indicate that all data binding classes should be generated into the JAR file specified in the JAR File field. You must generate all data binding classes into a single JAR file whenever there are cyclical references between schema files.

Use this JAR for All Data Bindings

Invokes a dialog where you can set the folder to contain generated JAR files:

Set JAR Folder

• All Generated JARs - All JAR files will be generated in the same folder as the destination of the currently selected JAR.

• New Generated JARs - Only newly generated JAR files will be generated in the same folder as the destination of the currently selected JAR file.

Setting the JAR folder affects only the JAR files generated by the wizard. It has no effect outside the wizard nor on subsequent wizard runs.

Default: All Generated JARs.

The status of the JAR file containing the classes generated for the selected contract:

JAR Status

• JAR is non-existent and will be generated. - The JAR file does not exist.

• Different binding type. JAR must be overwritten. - The value of the Type field is different than the type of the data binding classes in the JAR file.

• JAR exists and will be overwritten. - The JAR file exists and the Overwrite Existing

(36)

Enabled only when the JAR file exists. When checked, the JAR file will be regenerated.

When unchecked, the existing file will be reused and will not be modified.

Overwrite Existing JAR

Advanced

Indicate that all packages of classes generated into the same plug-in as the component implementation should be exported in the component's implementation plug-in Export Data Binding

Packages

manifest using the Export-Package directive. This allows you to reuse data binding JAR files generated into the same plug-in as the component implementation. However, this is not the recommended approach for data binding library sharing. Instead you should generate data binding JAR files into a separate plug-in project.

Default: Unchecked.

Indicate that the specified data binding configuration file should be used when generating JAR files. When you check the checkbox, the text field is enabled.

Default: Unchecked.

Use Configuration File

Related Topics

Generating a Java Component Implementation on page 32 Default XML to Java Mapping on page 83

(37)

Regenerating a Java Component Implementation

Before you begin

The implementation must have been originally generated by TIBCO Business Studio.

About this task

You should regenerate the component implementation after you add a service, reference, or property to the component or to recreate the data binding classes created by a previous version of TIBCO Business Studio.

The regeneration will regenerate the abstract class, but it will not change or remove any code from the implementation class. It is possible that the implementation class will have errors after regeneration (for example when the reference has been removed and the implementation is using the reference).

If the implementation was generated with a previous version of TIBCO Business Studio, a dialog displays asking if you want to delete legacy JARs. Legacy JARs are named PortType-timestamp-service-beans.jar

and PortType-timestamp-service-interface.jar. Procedure

Canvas 1. Right-click the component and select Regenerate Java Implementation.

Problems View 1. In the Problems view, right-click an error of the form The component

"ComponentName" is out of sync with its implementation and select Quick Fix.

2. In the Quick Fix dialog select Update Implementation Class.

Command Line 1. Create a command-line build file and specify an

sds.javait.regenerateComponent task. For example:

<sds.javait.regenerateComponent projectName="MyProject"

compositeName="MyComposite"

componentName="MyJavaComponent" />

2. Run the command-line with the build file.

2. Decide how you want to handle legacy JARs and follow the appropriate procedure.

Procedure Legacy JARs

Delete 1. Click Yes.

(38)

The implementation is updated to match the component.

(39)

Upgrading a Java Component Implementation

About this task

Perform these steps after you modify a component implementation.

Procedure

1. Open the plug-in manifest of the plug-in containing the component implementation.

a) In the Overview tab, increment the appropriate version component of the plug-in. For example, if you add a property, change 1.0.0.qualifier to 1.1.0.qualifier.

b) In the Runtime tab, increment the appropriate version component of the exported package. For example, if you add a property, change 1.0.0.qualifier to 1.1.0.qualifier.

c) Save the manifest.

2. Open the custom feature containing the plug-in.

a) In the Overview tab, increment the appropriate version component of the feature. For example, if you add a property, change 1.0.0.qualifier to 1.1.0.qualifier.

b) In the Plug-ins tab, increment the appropriate version component of the included plug-in. For example, if you add a property, change 1.0.0.qualifier to 1.1.0.qualifier.

c) Save the feature.

(40)

Life Cycle Events

The TIBCO ActiveMatrix runtime exposes component life cycle events—Init and Destroy—to component implementations. Methods annotated with @Init and @Destroy are invoked when the life cycle events trigger.

Table 3: Life Cycle Events on page 40 describes the meaning of each event and how component implementations can handle each event.

Table 3: Life Cycle Events

When Invoked Event

When the application containing the component or the component is started.

When this event is triggered all the component's properties, references, and resources have been initialized.

Init

The method invoked when this event is triggered is typically used to validate component configuration and open connection to resources.

When the application containing the component or the component is stopped.

Destroy

If you open connections to resources in a method that is invoked by an Init event you must close the connections to the resources in the method that is invoked by a Destroy event.

When TIBCO Business Studio generates a Java or Spring component implementation, it automatically adds the appropriately annotated initialization and destruction methods:

org.osoa.sca.annotations.Init;

org.osoa.sca.annotations.Destroy;

@Init

public void init() {

// Component initialization code.

// All properties are initialized and references are injected.

}

@Destroy

public void destroy() { // Component disposal code.

// All properties are disposed.

}

You can customize these methods to perform application-specific initialization and cleanup.

(41)

Component Context

A component context provides access to the context in which a component executes. The context includes the component's name and containing application name, the node on which it executes, the host managing the node, context parameters available to the component, the component's work area, and so on.

To access the component context, add the following declarations to a Java or Spring component implementation:

import org.osoa.sca.annotations.Context;

import com.tibco.amf.platform.runtime.extension.context.ComponentContext;

@Context

public ComponentContext componentContext;

These declarations are automatically added to the abstract component implementation when a context parameter is defined for the component. The TIBCO ActiveMatrix platform injects the component context object into the component implementation.

If a component implementation wants to create a file, it should do so in the work area assigned to each component. The TIBCO ActiveMatrix platform ensures that these files are deleted when the component is undeployed. Work areas are backed up during node upgrade. A component implementation can retrieve its work area through the component context's getWorkArea() method which returns the java.io.File object that represent the work area folder for that component.

Related Topics

Accessing a Context Parameter on page 62 Java API Reference on page 73

(42)

Accessing a Property

About this task

When you generate a Java or Spring component implementation after adding a property to the component, TIBCO Business Studio adds the following to the component's abstract implementation class:

• SCA property annotation import

• A field that represents the property

• Accessor methods

The TIBCO ActiveMatrix platform injects the property object into the component implementation.

For example, if you add a property named ^greeting of type ^String to a component, the following code is added:

org.osoa.sca.annotations.Property;

private String greeting;

@Property(name = "greeting")

public void setGreeting(String greeting) { this.greeting = greeting;

}

public String getGreeting() { return greeting;

}

Procedure

To reference the property invoke the accessor methods. For example:

resp.setHelloResponse(getGreeting() + " " + name + "! "

+ "The current time is " + time + ".");

(43)

Accessing a Resource

Procedure

1. Add a property of the resource type to the component.

2. Generate or regenerate the component implementation. TIBCO Business Studio adds imports, fields, and resource accessor methods to the component's abstract implementation class. When the component is instantiated, the TIBCO ActiveMatrix platform injects the resource object into the component

implementation.

3. Access the resource using the generated accessor methods.

4. After you are finished with the resource and any objects retrieved from the resource, close the objects.

Related Topics

Java API Reference on page 73

Accessing a Hibernate Resource

About this task

If you create a property named sessionFactory of type Hibernate Resource Template, TIBCO Business Studio adds the following to the abstract implementation class:

import org.osoa.sca.annotations.Property;

import

com.tibco.amf.sharedresource.runtime.core.hibernate.sharedresource.ProxySessionFactory;

private ProxySessionFactory sessionFactory;

@Property(name = "sessionFactory")

public void setSessionFactory(ProxySessionFactory sessionFactory) { this.sessionFactory = sessionFactory;

}

public ProxySessionFactory getSessionFactory() { return sessionFactory;

}

Procedure

1. Retrieve the proxy session factory using the generated getSessionFactory method.

2. Register the model class using the session factory ^addClass method.

3. Retrieve the Hibernate session from the session factory using the openSession method.

4. Retrieve a transaction from the session.

5. Create a query.

(44)

final Session session = getSessionFactory().openSession();

try { /**

* Begin a transaction before performing any queries.

* Closing the session cleans up the transaction.

*/

Transaction tx = session.beginTransaction();

final Query query = session.createQuery("UPDATE ...");

...

int result = query.executeUpdate();

if (result == 0) { ...

session.save(report);

}

tx.commit();

} finally { session.close();

} ...

@Init

public void init() {

if (getSessionFactory() == null) {

throw new IllegalStateException("Failed to inject ProxySessionFactory");

}

/*** Register the ModelClass model class on SessionFactory */

getSessionFactory().addClass(ModelClass^.class);

try {

// Initializes database data.

initializeDBData();

} catch (Throwable th) { ...

} } ...

@Destroy

public void destroy() {

if (getSessionFactory() != null) { /**

* Unregister the ModelClass model class from SessionFactory */

getSessionFactory().removeClass(ModelClass^.class);

} }

Accessing a JDBC Resource

About this task

If you create a property named jdbcr of type JDBC Resource Template, TIBCO Business Studio adds the following to the abstract implementation class:

import org.osoa.sca.annotations.Property;

import javax.sql.DataSource;

private DataSource jdbcr;

@Property(name = "jdbcr")

public void setDbr(DataSource jdbcr) { this.jdbcr = jdbcr;

}

public DataSource getJdbcr() { return jdbcr;

}

Procedure

Invoke the accessor methods in your component implementation.

Example

import javax.sql.DataSource;

DataSource ds = getJdbcr();

Connection connection = null;

(45)

try {

connection = ds.getConnection();

ensureTablesExist(connection);

Statement stmt = connection.createStatement();

ResultSet rs = stmt.executeQuery(sqlString);

PhoneEntryType entry = null;

while(rs.next()) {

entry = resp.addNewOut();

entry.setEntryId(rs.getString("id"));

entry.setFirstName(rs.getString("firstName"));

entry.setLastName(rs.getString("lastName"));

entry.setPhone(rs.getString("phone"));

}

} catch(SQLException e) { e.printStackTrace();

} finally { try{

connection.close();

}catch(Exception e){};

...

} }

Accessing JMS Resources

About this task

To access JMS resources, create JMS Connection Factory and JMS Destination properties. If you create a property named connectionFactory of type JMS Connection Factory and a property named destination of type JMS Destination, TIBCO Business Studio adds the following to the abstract implementation class:

import javax.jms.ConnectionFactory;

import javax.jms.Destination;

private ConnectionFactory connectionFactory;

@Property(name = "connectionFactory")

public void setConnectionFactory(ConnectionFactory connectionFactory) { this.connectionFactory = connectionFactory;

}

public ConnectionFactory getConnectionFactory() { return connectionFactory;

}

private Destination destination;

@Property(name = "destination")

public void setDestination(Destination destination) { this.destination = destination;

}

public Destination getDestination() { return destination;

}

Procedure

Invoke the accessor methods in your component implementation.

TIBCO ActiveMatrix