Contents

Preface

Overview of the Sun ONE Connector Builder

Application Integration
Introduction
Key Features
Key Features of the Generated Resource Adapters
Basic Concepts

Common Client Interface (CCI)
Service Provider Interface (SPI)
EIS API
Resource Adapter
Java Interaction Object (JIO)
SOAP Services

Development Process
Runtime Deployment Scenarios

Deployment in Managed Environment
Deployment in Non-managed Environment
Deployment in Managed Environment with SOAP over HTTP/S
Deployment in Non-managed Environment with SOAP over HTTP/S

General Approach for Building Resource Adapters

Classifying EIS APIs

Classifying by Implementation Language
Classifying by Connection Style

Connection-oriented EIS APIs
Connection-less EIS APIs

Classifying by Method Input and Output Data Style
Classifying by API Abstraction Level

Specific EIS APIs - Application Vocabulary
General-purpose EIS APIs - Software Vocabulary

Working With Different Types of EIS APIs

The Model EIS API
Considering Implementation Language
Considering Method Input and Output Data Styles

Data via Parameters and Return Values Only
Data via Object State
Data via Environment

Considering Connection Style

Background
Connection-less
Connection-as-parameter
Connection-as-target

Considering EIS API Abstraction Level

Specific EIS APIs
General-purpose EIS APIs

Summarizing EIS API Classification

Creating the Resource Adapter

Mounting the EIS API
Defining the Resource Adapter

Step 1 - Template Chooser

From the IDE main menu
From the IDE Explorer Area

Step 2 - Specifying Adapter Location Information
Step 3 - Entering Adapter General Information
Step 4 - Mapping the EIS API

Identifying Connection Objects

Step 5 - Customizing Interaction Specs

Change the Name of the InteractionSpec and Records
Set JIO Options

Step 6 - Specifying Configuration Properties
Step 7 - Choosing Authentication and Transactional Support
Step 8 - Enter Licensing Information
Step 9 - Set Adapter Icons

Generating the Resource Adapter

Internationalization Support For Generated Code

Understanding the Resource Adapter Directory Structure
How the Resource Adapter is Displayed in the IDE

Modifying the Resource Adapter Definition

How to Modify Resource Adapter Definitions

Displaying the Adapter's Contextual Menu
Choosing the Action
Edit EIS API Data
Edit InteractionSpec
Edit Template InteractionSpec
Edit Configuration Properties
Configure SOAP Services
View Deployment Descriptor
Generate
Import Files
Build
Build All
Package
Delete
Save
Help
Properties

Basic Properties Tab
Deployment Properties Tab
Modifying the Large and Small Icon
Changing Transaction Support

Saving the Modifications
Regenerating an Adapter

Security

Customizing the Generated Resource Adapter

Overview of Customizations
Customizable Elements of Generated Resource Adapters

Categorizing Generated Classes by Class Hierarchy

Level 1 Classes
Level 2 Classes
Level 3 Classes

Categorizing Generated Classes by Functional Responsibility

Classes for Invoking the EIS API
Classes for Managing Connections, Transactions, and Security
Java Interaction Object (JIO) Classes

Naming Conventions for Generated Classes
Generated Properties Files

General Approach to Customizing Sun ONE Connector Builder Resource Adapters

Customizing the Properties Files

<adapterLogicalName>log.properties
<adapterLogicalName>RAMD.properties
<adapterLogicalName>.properties

General Approach to Customizing Java Classes

Preserving Customizations
Customization Points and Categories of Customization

Customizing the Resource Adapter

Mandatory Customization Points

Mandatory Customizations Related to EIS API Method Invocation
Mandatory Customizations Related to Connections, Transactions, and Security
Methods for Cleaning Up and Destroying a Physical Connection

Basic Customization Points

Basic Customizations Related to EIS API Method Invocation
Basic Customizations Related to Connections, Transactions, and Security

Customizing the Resource Adapter's JIOs

JIO Class Naming Scheme
The Execute and ExecuteAPI Methods
Generated JIO - Code Sample
JIO Generation Options

Expose Function Name
Start Local Transaction

Advanced Customizations (optional)

Provide Connection Spec Properties for getConnection Call
Embedding Extra Log Messages in JIO
Restricting Usage of the Connector at Runtime
Preserving Customizations to the JIOs

Adding SOAP Services to the Resource Adapter

Basic Concepts

What is SOAP?

How Does SOAP Work?
SOAP Processing

Generating SOAP Services for Connector Builder Resource Adapters

Editing the Serializer
Editing the Participating Classes
Editing a Serializer
Editing a Participating Class

Customizing the SOAP Layer

SOAP Service Generation Naming Scheme
Generated SOAP Framework - Code Samples

Template Serializer/Deserializer
Service Deployment Descriptor
HTTP Client

Mandatory Customizations

Implementing the Serializers
HTTP Client Modifications

Advanced Customizations (Optional)

Service URN Modifications
Using HTTPS with SOAP Clients
Propagating Adapter Internal Exceptions to SOAP Clients

Preserving Customizations

Building/Packaging the Generated Resource Adapter

Overview
The Generated ANT Build XML File
Preparing to Build/Package the Generated Resource Adapter
How to Build/Package the Generated Resource Adapter from within the IDE
How to Build/Package the Generated Resource Adapter from Outside the IDE
Verifying ANT Execution Output

Deploying the Resource Adapter

Deployment Scenarios

Deployment in Managed Environment

With SOAP over HTTP/S

Deployment in Non-Managed Environment

With SOAP over HTTP/S

Deploying the Resource Adapters

Deploying the Resource Adapters in Non-managed Environments
Deployment Process for Non-managed Environments
Step 1 - Register Deployment Platform Instance (icsvrreg)

Examples

Step 2 - Deploy Resource Adapter (icradeploy)

Examples

Step 3 - Configure Connection Factory (icconfig)

Examples
Adding a Connection Factory
Updating an Existing Connection Factory's Parameters

Step 4- Deploy SOAP Services (icwsdeploy) - optional

Examples

Step 5- Check the Version of Sun ONE Connector Builder (icversion) - optional

Examples

Using the Resource Adapters

Using CCI
Using JIO
Using SOAP

Testing the Generated Resource Adapter

Introduction to TestClient

Key Features of TestClient
Key Components of TestClient

Test Harness
Test Servlet Router

TestClient Runtime Processing

Building Test Cases

Developing Test Cases

public void setup(Properties prop) throws Exception
public void test() throws Exception
public void cleanup() throws Exception
Example of a Test Case

Packaging and Deploying Test Cases

Configuration Files

Test List File
Exclude List File
TestSetup Properties File
Testrun Parameters File

Deploying the Test Servlet Router

Verifying Successful Deployment of the Test Servlet Router

Running the TestClient

Examining the Test Results

Running the TestClient with Sample Adapters

Administration and Monitoring of the Generated Resource Adapter

Logging

Adapter Log Configuration File
Log Configuration Parameters

Log Level
List of Handlers (logging output destinations)
StreamHandler Configurable Parameters
FileHandler Configurable Parameters

Sample Adapter Log Configuration File
Logging APIs

ICONLogger
ICONLogLevel

How to Access a Logger Instance within Generated Adapter Code
Logging by Generated Resource Adapters

Connection Pooling

Pool Configuration Parameters

J2EE Connector Architecture

Command Line Interface Reference

icsvrreg

Description
Usage
Subcommands
Options
Examples
Environment Variables
Exit Status
See Also
Diagnostics
Notes

icradeploy

Description
Usage
Subcommands
Options
Examples
Environment Variables
Exit Status
See Also
Diagnostics
Notes

icconfig

Description
Usage
Subcommands
Options
Examples
Environment Variables
Exit Status
See Also
Diagnostics
Notes

icwsdeploy

Description
Usage
Subcommands
Options
Examples
Environment Variables
Exit Status
See Also
Diagnostics
Notes

ictstclnt

Description
Usage
Options
Examples
Environment Variables
Exit Status
Diagnostics
Notes

icversion

Description
Usage
Examples
Environment Variables
Exit Status
Diagnostics

Installing Apache SOAP 2.2

Overview
Installing Apache SOAP 2.2 on iPlanet Web Server 6.0

Configuring iWS with JDK1.3.1
Add Apache SOAP Runtime and Other Jar Files to the iWS Classpath
Deploying Apache SOAP Web Application Module (soap.war)
Verifying Your Installation

HTTP Transport Support Verification
Deployment Tools Verification

Installing Apache SOAP 2.2 on J2EE Reference Implementation (J2EE RI) 1.3.1

Add Apache SOAP Runtime and Other Jar Files to the J2EE RI Classpath
Deploy Apache SOAP Web Application Module (soap.war)
Verifying Your Installation

HTTP Transport Support Verification
Deployment Tools Verification

Installing Apache SOAP 2.2 on iPlanet Application Server 6.5
Installing Apache SOAP 2.2 on Sun ONE Application Server 7

Working with Sun ONE Integration Server

Overview
Deploy the Adapter's SOAP Services
Define the SOAP Services in Integration Server

Sample Backbone/Proxy Definition

Datatype Mappings

Trouble Shooting

Development Time
Sun ONE Application Server 7.0
Web Server
J2EE 1.3 Reference Implementation (J2EE RI)
Logging
Samples
SOAP

Working with C/C++ API

Bringing the Legacy C, C++ API to Java

Runtime Requirements

Internationalization

Multi-byte Character Limitations

Glossary

Index