Sun SeeBeyond eWay(TM) File Adapter User`s Guide

SUN SEEBEYOND
eWAY™ FILE ADAPTER
USER’S GUIDE
Release 5.1.2
Copyright © 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Sun
Microsystems, Inc. has intellectual property rights relating to technology embodied in the product that is described in this
document. In particular, and without limitation, these intellectual property rights may include one or more of the U.S. patents
listed at http://www.sun.com/patents and one or more additional patents or pending patent applications in the U.S. and in
other countries. U.S. Government Rights - Commercial software. Government users are subject to the Sun Microsystems, Inc.
standard license agreement and applicable provisions of the FAR and its supplements. Use is subject to license terms. This
distribution may include materials developed by third parties. Sun, Sun Microsystems, the Sun logo, Java, Sun Java Composite
Application Platform Suite, SeeBeyond, eGate, eInsight, eVision, eTL, eXchange, eView, eIndex, eBAM, eWay, and JMS are
trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. All SPARC trademarks are used
under license and are trademarks or registered trademarks of SPARC International, Inc. in the U.S. and other countries.
Products bearing SPARC trademarks are based upon architecture developed by Sun Microsystems, Inc. UNIX is a registered
trademark in the U.S. and other countries, exclusively licensed through X/Open Company, Ltd. This product is covered and
controlled by U.S. Export Control laws and may be subject to the export or import laws in other countries. Nuclear, missile,
chemical biological weapons or nuclear maritime end uses or end users, whether direct or indirect, are strictly prohibited.
Export or reexport to countries subject to U.S. embargo or to entities identified on U.S. export exclusion lists, including, but
not limited to, the denied persons and specially designated nationals lists is strictly prohibited.
Copyright © 2006 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, Etats-Unis. Tous droits réservés.
Sun Microsystems, Inc. détient les droits de propriété intellectuels relatifs à la technologie incorporée dans le produit qui est
décrit dans ce document. En particulier, et ce sans limitation, ces droits de propriété intellectuels peuvent inclure un ou plus
des brevets américains listés à l'adresse http://www.sun.com/patents et un ou les brevets supplémentaires ou les
applications de brevet en attente aux Etats - Unis et dans les autres pays. L'utilisation est soumise aux termes de la Licence.
Cette distribution peut comprendre des composants développés par des tierces parties. Sun, Sun Microsystems, le logo Sun,
Java, Sun Java Composite Application Platform Suite, Sun, SeeBeyond, eGate, eInsight, eVision, eTL, eXchange, eView, eIndex,
eBAM et eWay sont des marques de fabrique ou des marques déposées de Sun Microsystems, Inc. aux Etats-Unis et dans
d'autres pays. Toutes les marques SPARC sont utilisées sous licence et sont des marques de fabrique ou des marques déposées
de SPARC International, Inc. aux Etats-Unis et dans d'autres pays. Les produits portant les marques SPARC sont basés sur une
architecture développée par Sun Microsystems, Inc. UNIX est une marque déposée aux Etats-Unis et dans d'autres pays et
licenciée exclusivement par X/Open Company, Ltd. Ce produit est couvert à la législation américaine en matière de contrôle
des exportations et peut être soumis à la règlementation en vigueur dans d'autres pays dans le domaine des exportations et
importations. Les utilisations, ou utilisateurs finaux, pour des armes nucléaires, des missiles, des armes biologiques et
chimiques ou du nucléaire maritime, directement ou indirectement, sont strictement interdites. Les exportations ou
réexportations vers les pays sous embargo américain, ou vers des entités figurant sur les listes d'exclusion d'exportation
américaines, y compris, mais de manière non exhaustive, la liste de personnes qui font objet d'un ordre de ne pas participer,
d'une façon directe ou indirecte, aux exportations des produits ou des services qui sont régis par la législation américaine en
matière de contrôle des exportations et la liste de ressortissants spécifiquement désignés, sont rigoureusement interdites.
Part Number: 819-7404-10
Version 20061004085437
File eWay User’s Guide
2
Sun Microsystems, Inc.
Contents
Contents
Chapter 1
Introducing the File eWay
5
About the File eWay
5
eWay Operation
Setting Properties
5
6
What’s New in This Release
6
About This Document
6
What’s in this Document
File eWay Javadoc
Scope
Intended Audience
Text Conventions
7
7
7
7
7
Sun Microsystems, Inc. Web Site
8
Documentation Feedback
8
Chapter 2
Installing the File eWay
9
File eWay System Requirements
9
Installing the File eWay
9
Installing the eWay on a JavaCAPS Supported System
Adding the eWay to an Existing Suite Installation
Installing eWay Enterprise Manager plug-ins
File eWay Alert Codes
After Installation
ICAN 5.0 Project Migration Procedures
10
10
11
11
13
13
Chapter 3
Configuring the File eWay
15
Configuring the File eWay Properties
15
Selecting File as the External Application
Accessing the eWay Properties
Modifying the eWay Properties
Modifying the eWay Connectivity Map Properties
File eWay User’s Guide
3
15
16
16
16
Sun Microsystems, Inc.
Contents
Modifying the eWay Environment Properties
Using the Properties Editor
16
17
Inbound File eWay Connectivity Map Properties
18
Parameter Settings
18
Outbound File eWay Connectivity Map Properties
Parameter Settings
20
20
File eWay Environment Properties
22
Inbound File eWay - Parameter Settings
Inbound File eWay - MDB Settings
Outbound File eWay - Parameter Settings
22
23
24
Chapter 4
Using the File eWay in a Project
25
File eWay Components
25
File OTD Operations
25
Using the File eWay with eInsight
26
Using the File eWay with Java-based Collaborations
26
Index
File eWay User’s Guide
27
4
Sun Microsystems, Inc.
Chapter 1
Introducing the File eWay
What’s in This Chapter
ƒ About the File eWay on page 5
ƒ What’s New in This Release on page 6
ƒ About This Document on page 6
ƒ Sun Microsystems, Inc. Web Site on page 8
1.1
About the File eWay
The File eWay Intelligent Adapter is a file-based eWay provided with the Sun Java™
Composite Application Platform Suite to support sample Projects and to test your Sun
Java™ Composite Application Platform Suite configuration. For a more feature-rich
solution to processing flat file records, we recommend that you use the Batch eWay
Intelligent Adapter. The Batch eWay provides a number of pre- and post-processing
features that the File eWay does not offer, including system rename, copy, and delete
operations that you can configure before and after you run a Collaboration, as well as
other features such as regular expression matching for filenames.
The File eWay exchanges data between an external file system and the Sun Java™
Composite Application Platform Suite. You can use this eWay for:
ƒ Reading information from an external file to the Sun Java™ Composite Application
Platform Suite.
ƒ Writing information from the Sun Java™ Composite Application Platform Suite to
an external file.
1.1.1
eWay Operation
The File eWay is provided as part of the Sun Java™ Composite Application Platform
Suite and operates as follows:
ƒ As an inbound eWay, the File eWay polls an input directory for files based on a file
name matching a specified regular expression. When the eWay detects a matching
file, it opens the file and publishes the data to a Collaboration or Business Process
Service.
ƒ As an outbound eWay, the eWay writes processed data to an output file.
File eWay User’s Guide
5
Sun Microsystems, Inc.
Chapter 1
Introducing the File eWay
1.1.2
Section 1.2
What’s New in This Release
Setting Properties
You can set configuration properties for the eWay, including names and locations of
source and destination files, in the eWay Properties dialog box, which is part of the
eGate™ Enterprise Designer. See Chapter 3 for more information about using the eWay
Properties dialog box.
For a description of a complete end-to-end scenario using the File eWay, inbound and
outbound, see the Sun SeeBeyond eGate™ Integrator Tutorial.
1.2
What’s New in This Release
The Sun SeeBeyond eWay File Adapter includes the following changes and new
features:
New for Version 5.1.2
ƒ This is a maintenance release. No new features.
New for Version 5.1.1
ƒ Supports automatic deployment of EAR files to WebLogic Application Server
(version 9.1).
New for Version 5.1.0
ƒ Version Control: An enhanced version control system allows you to effectively
manage changes to the eWay components.
ƒ Multiple Drag-and-Drop Component Mapping from the Deployment Editor: The
Deployment Editor now allows you to select multiple components from the
Editor’s component pane, and drop them into your Environment component.
ƒ Support for Runtime LDAP Configuration: eWay configuration properties now
support LDAP URL values.
ƒ MDB Pool Size Support: Provides greater flow control (throttling) by specifying the
maximum and minimum MDB pool size.
ƒ Connectivity Map Generator: Generates and links your Project’s Connectivity Map
components using a Collaboration or Business Process.
Many of these features are documented further in the Sun SeeBeyond eGate™ Integrator
User’s Guide or the Sun SeeBeyond eGate™ Integrator System Administrator Guide.
1.3
About This Document
This guide explains how to install, configure, and operate the Sun Java™ Composite
Application Platform Suite File eWay Intelligent Adapter, referred to as the File eWay
throughout this guide.
File eWay User’s Guide
6
Sun Microsystems, Inc.
Chapter 1
Introducing the File eWay
1.3.1
Section 1.3
About This Document
What’s in this Document
This document includes the following chapters:
ƒ Chapter 1 “Introducing the File eWay”: Provides an overview description of the
product as well as high-level information about this document.
ƒ Chapter 2 “Installing the File eWay”: Describes the system requirements and
provides instructions for installing the File eWay.
ƒ Chapter 3 “Configuring the File eWay”: Provides instructions for configuring the
eWay to communicate with external file system.
ƒ Chapter 4 “Using the File eWay in a Project”: Explains how to use the File eWay
within a Project that uses eInsight Business Processes or File Java Collaboration
Definitions.
1.3.2
File eWay Javadoc
The File eWay Javadoc defines the available Java methods provided with the File eWay.
The Javadoc is uploaded with the eWay’s documentation file, FileeWayDocs.sar, and is
downloaded from the Documentation tab of the Sun Java™ Composite Application
Platform Suite. To access the full Javadoc, extract the Javadoc to an easily accessible
folder and double-click index.html.
1.3.3
Scope
This document describes the process of installing, configuring, and running the File
eWay. For information on the File eWay’s Java methods, download and view the File
eWay Javadoc.
1.3.4
Intended Audience
This guide is intended for experienced computer users who have the responsibility of
helping to set up and maintain a fully functioning Java Composite Application
Platform Suite system. This person must also understand any operating systems on
which the Java Composite Application Platform Suite will be installed (Windows and
UNIX), and must be thoroughly familiar with Windows-style GUI operations.
1.3.5
Text Conventions
The following conventions are observed throughout this document.
Table 1 Text Conventions
Text Convention
Bold
File eWay User’s Guide
Used For
Examples
Names of buttons, files, icons,
parameters, variables, methods,
menus, and objects
7
ƒ Click OK.
ƒ On the File menu, click Exit.
ƒ Select the eGate.sar file.
Sun Microsystems, Inc.
Chapter 1
Introducing the File eWay
Section 1.4
Sun Microsystems, Inc. Web Site
Table 1 Text Conventions (Continued)
Text Convention
1.4
Used For
Examples
Monospaced
Command line arguments, code
samples; variables are shown in
bold italic
java -jar filename.jar
Blue bold
Hypertext links within
document
See Text Conventions on page 7
Blue underlined
Hypertext links for Web
addresses (URLs) or email
addresses
http://www.sun.com
Sun Microsystems, Inc. Web Site
The Sun Microsystems web site is your best source for up-to-the-minute product news
and technical support information. The site’s URL is:
http://www.sun.com
1.5
Documentation Feedback
We appreciate your feedback. Please send any comments or suggestions regarding this
document to:
CAPS_docsfeedback@sun.com
File eWay User’s Guide
8
Sun Microsystems, Inc.
Chapter 2
Installing the File eWay
This chapter contains installation information for the File eWay.
What’s in This Chapter
ƒ File eWay System Requirements on page 9
ƒ Installing the File eWay on page 9
ƒ ICAN 5.0 Project Migration Procedures on page 13
2.1
File eWay System Requirements
The File eWay Readme contains the latest information on:
ƒ Supported Operating Systems
ƒ System Requirements
ƒ External System Requirements
ƒ The File eWay Readme is uploaded with the eWay’s documentation file
(FileeWayDocs.sar) and can be accessed from the Documentation tab of the Sun
Java™ Integrator Suite Installer. Refer to the File eWay Readme for the latest
requirements before installing the File eWay.
2.2
Installing the File eWay
The Sun Java™ Composite Application Platform Suite Installer, a web-based
application, is used to select and upload eWays and add-on files during the installation
process. The following section describes how to install the components required for this
eWay.
Note: When the Repository is running on a UNIX operating system, the eWays are loaded
from the Enterprise Manager running on a Windows platform connected to the
Repository server using Internet Explorer.
File eWay User’s Guide
9
Sun Microsystems, Inc.
Chapter 2
Installing the File eWay
2.2.1
Section 2.2
Installing the File eWay
Installing the eWay on a JavaCAPS Supported System
Follow the directions for installing the Sun Java™ Composite Application Platform
Suite in the Sun Java™ Composite Application Platform Suite Installation Guide. After you
have installed eGate or eInsight, do the following:
1 From the Sun Java™ Composite Application Platform Suite Installer’s Select Sun
Java™ Composite Application Platform Suite Products to Install table
(Administration tab), expand the eWay option.
2 Select the products for your Sun Java™ Composite Application Platform Suite and
include the following:
Š FileeWay
To upload the File eWay User’s Guide, Help file, Javadoc, and Readme, select the
following:
Š FileeWayDocs
3 Once you have selected all of your products, click Next in the top-right or bottomright corner of the Select Sun Java™ Composite Application Platform Suite
Products to Install box.
4 From the Selecting Files to Install box, locate and select your first product’s SAR
file. Once you have selected the SAR file, click Next. Your next selected product
appears. Follow this procedure for each of your selected products. The Installation
Status window appears and installation begins after the last SAR file has been
selected.
5 Once your product’s installation is finished, continue installing the Sun Java™
Composite Application Platform Suite as instructed in the Sun Java™ Composite
Application Platform Suite Installation Guide.
Adding the eWay to an Existing Suite Installation
If you are adding the eWay to an existing Sun Java™ Composite Application Platform
Suite installation, do the following:
1 Complete steps 1 through 4 above.
2 Once your product’s installation is finished, open the Enterprise Designer and
select Update Center from the Tools menu. The Update Center Wizard appears.
3 For Step 1 of the wizard, simply click Next.
4 For Step 2 of the wizard, click the Add All button to move all installable files to the
Include in Install field, then click Next.
5 For Step 3 of the wizard, wait for the modules to download, then click Next.
6 The wizard’s Step 4 window displays the installed modules. Review the installed
modules and click Finish.
7 When prompted, restart the IDE (Integrated Development Environment) to
complete the installation.
File eWay User’s Guide
10
Sun Microsystems, Inc.
Chapter 2
Installing the File eWay
2.2.2
Section 2.2
Installing the File eWay
Installing eWay Enterprise Manager plug-ins
The Sun SeeBeyond Enterprise Manager is a Web-based interface that allows you to
monitor and manage your Java Integration Suite applications. The Enterprise Manager
requires an eWay specific “plug-in” for each of your installed eWays. These plug-ins
enable the Enterprise Manager to target specific alert codes for each eWay type, as well
as to start and stop the inbound eWays.
The Sun Java™ Composite Application Platform Suite Installation Guide describes how to
install the Sun SeeBeyond Enterprise Manager. The Sun SeeBeyond eGate™ Integrator
System Administration Guide describes how to monitor servers, Services, logs, and alerts
using the Sun SeeBeyond Enterprise Manager and the command-line client.
The eWay Enterprise Manager plug-ins are available from the List of Components to
Download under the Sun Java™ Composite Application Platform Suite Installer’s
DOWNLOADS tab.
There are two ways to add the eWay Enterprise Manager plug-ins:
1 From the Enterprise Manager:
A From the Enterprise Manager’s Explorer toolbar, click the Configuration icon.
B Click the Web Applications Manager tab, go to the Auto-Install from
Repository tab, and connect to your Repository.
C Select the application plug-ins you require, and click Install. The application
plug-ins are installed and deployed.
2 From the Sun Java™ Composite Application Platform Suite Installer:
A From the Sun Java™ Composite Application Platform Suite Installer’s
Download tab, select the Plug-Ins you require and save them to a temporary
directory.
B Log onto the Sun SeeBeyond Enterprise Manager. From the Enterprise
Manager’s Explorer toolbar, click the Configuration icon.
C Click the Web Applications Manager tab and the Manage Applications tab.
D Browse for and select the EMR file for the application plug-in that you
downloaded, and click Deploy. The plug-in is installed and deployed.
File eWay Alert Codes
You can view and delete alerts using the Enterprise Manager. An alert is triggered
when a specified condition occurs in a Project component. The purpose of the alert is to
warn the administrator or user that a condition has occurred.
To View the eWay Alert Codes
1 Add the eWay Enterprise Manager plug-in for this eWay.
2 From the Enterprise Manager’s Explorer toolbar, click the Configuration icon.
3 Click the Web Applications Manager tab and go to the Manage Alert Codes tab.
Your installed alert codes are displayed under the Results section. If your eWay
alert codes are not available displayed under Results, do the following
File eWay User’s Guide
11
Sun Microsystems, Inc.
Chapter 2
Installing the File eWay
Section 2.2
Installing the File eWay
A From the Install New Alert Codes section, browse to and select the eWay alert
properties file for the application plug-in that you added. The alert properties
files are located in the alertcodes folder of your Sun Java Composite Application
Platform Suite installation directory.
B Click Deploy. The available alert codes for your application are displayed under
Results. A listing of available this eWay’s alert codes is displayed in Table 2.
Table 2 File eWay Alert Codes
Alert Code
Description
User Action
FILEASCANTCREATEINPUTDIR000004
Unable to create input
directory {0}
Make sure that the user has
permissions to create the directory.
FILEASINPUTDIRNONEXISTENT000002
Input directory {0} does
not exist. Creating the
directory. This is a
warning.
Verify that the input directory is
named correctly. The directory may
not have the expected name.
Check for spelling mistakes.
FILE-ASINPUTDIRNOTDIR000003
Input directory {0} is
not a directory
The directory name may be an
existing filename. Verify that the
directory name is not the same as
an existing file name.
FILE-ASRENAMEFAILED000001
Failed attempting to
rename input file {0}
ƒ Verify that the file permissions
for your input file are not readonly.
ƒ If this occurs when renaming a
file to text the eWay, make sure
that a file with this name does
not already exist. For example, if
you are renaming the input1.txt
file to input1.txt.~in, and an ~in
file already exists, the rename
will fail.
FILECANTWRITEOUTPUTDIR000005
Error writing to output
directory {0}
ƒ Verify that the output directory
exists.
ƒ Verify that the output directory
has write permissions.
ƒ Make sure that there is enough
disk space to write to the disk.
FILECANTWRITEOUTPUTFILE000006
Error writing to output
file {0}
ƒ Verify that the output directory
exists.
ƒ Verify that the output directory
has write permissions.
ƒ Make sure that there is enough
disk space to write to the disk.
An alert code is a warning that an error has occurred. It is not a diagnostic. The user
actions noted above are possible corrective measures you may take. Refer to your log
files for more information. For information on Managing and Monitoring alert codes
and logs, see the Sun SeeBeyond eGate Integrator System Administration Guide.
File eWay User’s Guide
12
Sun Microsystems, Inc.
Chapter 2
Installing the File eWay
2.2.3
Section 2.3
ICAN 5.0 Project Migration Procedures
After Installation
Once the eWay is installed and configured it must then be incorporated into a Project
before it can perform its intended functions. See the eGate Integrator User’s Guide for
more information on incorporating the eWay into an eGate Project.
2.3
ICAN 5.0 Project Migration Procedures
This section describes how to transfer your current ICAN 5.0 Projects to Sun Java
Composite Application Platform Suite, version 5.1.2. Only Projects developed on ICAN
version 5.0.2 and above can be migrated successfully to the Sun Java Composite
Application Platform Suite. To migrate your ICAN 5.0 Projects, do the following:
Export the Project
1 Before you export your Projects, save your current ICAN 5.0 Projects to your
Repository.
2 From the Project Explorer, right-click your Project and select Export from the
shortcut menu. The Export Manager appears.
3 Select the Project that you want to export in the left pane of the Export Manager and
move it to the Selected Projects field by clicking the Add to Select Items (arrow)
button, or click All to include all of your Projects.
4 In the same manner, select the Environment that you want to export in the left pane
of the Export Manager and move it to the Selected Environments field by clicking
the Add to Select Items (arrow) button, or click All to include all of your
Environments.
5 Browse to select a destination for your Project ZIP file and enter a name for your
Project in the ZIP file field.
6 Click Export to create the Project ZIP file in the selected destination.
Install Sun Java Composite Application Platform Suite
7 Install the Sun Java Composite Application Platform Suite, including all eWays,
libraries, and other components used by your ICAN 5.0 Projects.
8 Start the Sun SeeBeyond Enterprise Designer.
Import the Project
9 From the Enterprise Designer’s Project Explorer tree, right-click the Repository and
select Import Project from the shortcut menu. The Import Manager appears.
10 Browse to and select your exported Project file.
11 Click Import. A warning message, “Missing APIs from Target Repository,” may
appear at this time. This occurs because various product APIs were installed on the
ICAN 5.0 Repository when the Project was created, that are not installed on the Sun
Java Composite Application Platform Suite Repository. These APIs may or may not
apply to your Projects. You can ignore this message if you have already installed all
File eWay User’s Guide
13
Sun Microsystems, Inc.
Chapter 2
Installing the File eWay
Section 2.3
ICAN 5.0 Project Migration Procedures
of the components that correspond to your Projects. Click Continue to resume the
Project import.
12 Close the Import Manager after the Project is successfully imported.
Deploy the Project
13 A new Deployment Profile must be created for each of your imported Projects.
When a Project is exported, the Project’s components are automatically “checked in”
to Version Control to write-protected each component. These protected components
appear in the Explorer tree with a red padlock in the bottom-left corner of each icon.
Before you can deploy the imported Project, the Project’s components must first be
“checked out” of Version Control from both the Project Explorer and the
Environment Explorer. To “check out” all of the Project’s components, do the
following:
A From the Project Explorer, right-click the Project and select Version Control >
Check Out from the shortcut menu. The Version Control - Check Out dialog box
appears.
B Select Recurse Project to specify all components, and click OK.
C Select the Environment Explorer tab, and from the Environment Explorer, rightclick the Project’s Environment and select Version Control > Check Out from
the shortcut menu.
D Select Recurse Environment to specify all components, and click OK.
14 If your imported Project includes File eWays, these must be reconfigured in your
Environment prior to deploying the Project. To reconfigure your File eWays, do the
following:
A The Environment File External System properties can now accommodate both
inbound and outbound eWays. If your previous Environment includes both
inbound and outbound File External Systems, delete one of these (for example,
the outbound File External System).
B From the Environment Explorer tree, right-click your remaining File External
System, and select Properties from the shortcut menu. The Properties Editor
appears.
C The Directory property has been relocated from the Connectivity Map
Properties to the Environment Properties. Set the inbound and outbound
Directory values, and click OK.
15 Deploy your Projects.
Note: Only projects developed on ICAN 5.0.2 and above can be imported and migrated
successfully into the Java Integration Suite.
File eWay User’s Guide
14
Sun Microsystems, Inc.
Chapter 3
Configuring the File eWay
This chapter explains how to set the properties for the File eWay.
Chapter Topics
ƒ Configuring the File eWay Properties on page 15
ƒ Inbound File eWay Connectivity Map Properties on page 18
ƒ File eWay Environment Properties on page 22
3.1
Configuring the File eWay Properties
The File eWay includes a unique set of configuration parameters. After creating the
eWays and the File External System in the Project’s Environment, the property
parameters can be modified for your specific system.
3.1.1
Selecting File as the External Application
To create a File eWay you must first create a File External Application in your
Connectivity Map. File eWays are located between a File External Application and a
Service. Services are containers for Java Collaborations, Business Processes, eTL
processes, and so forth.
To create a File External Application
1 From the Connectivity Map toolbar, click the External Applications icon.
2 Select the File External Application from the menu (see Figure 1). The selected File
External Application icon appears on the Connectivity Map toolbar.
Figure 1 External Applications Selection Menu
The new External System can now be dragged and dropped onto the Connectivity
Map canvas and incorporated into a Project.
File eWay User’s Guide
15
Sun Microsystems, Inc.
Chapter 3
Configuring the File eWay
3.1.2
Section 3.1
Configuring the File eWay Properties
Accessing the eWay Properties
When you connect (bind) an External Application to a Service/Collaboration/Business
Process, the Enterprise Designer automatically assigns the appropriate eWay to the link
(see Figure 2). In the case of the File eWay, the direction of the data, to or from the
service, determines whether the eWay is inbound or outbound, and the appropriate
properties template is assigned to the eWay. Each eWay retains a properties template
containing its default configuration properties that are accessible from the Connectivity
Map and Environment Explorer.
Figure 2 Connectivity Map - File eWay
File eWay
(inbound)
3.1.3
File eWay
(outbound)
Modifying the eWay Properties
The eWay properties can be modified after the eWays have been created in the
Connectivity Map and the Project’s Environment has been created. The File eWay
properties are modified from two locations: the Connectivity Map and the Environment
Explorer.
Modifying the eWay Connectivity Map Properties
The Connectivity Map properties most commonly apply to a specific component eWay,
and may vary from other eWays (of the same type) in the Project.
1 From the Connectivity Map, double click the eWay icon, located in the link between
the associated External Application and the Service.
2 The eWay Properties Editor opens with the eWay’s Connectivity Map properties
(either inbound or outbound). Make any necessary modifications and click OK to
save the settings.
Modifying the eWay Environment Properties
These parameters are commonly global, applying to all eWays (of the same type) in the
Project. The saved properties are shared by all eWays for the specified External System.
1 From the Environment Explorer tree, right-click the File External System. Select
Properties from the shortcut menu. The Properties Editor opens with the eWay
Environment properties.
2 Make any necessary modifications to the Environment properties, and click OK to
save the settings.
File eWay User’s Guide
16
Sun Microsystems, Inc.
Chapter 3
Configuring the File eWay
3.1.4
Section 3.1
Configuring the File eWay Properties
Using the Properties Editor
You can modify your eWay properties using the eWay Properties Editor.
Modifying the Default eWay Properties
1 From the upper-left pane of the Properties Editor, select a subdirectory of the
Properties tree. The parameters contained in that subdirectory are now displayed in
the right pane of the Properties Editor. For example, clicking on the Parameter
Settings subdirectory displays the editable parameters in the right pane, as shown
in Figure 3 on page 17.
Figure 3 Properties Editor - File eWay
2 Click on any property field to make it editable. For example, click on the Encoding
property to edit the properties settings. For properties that have a value of true/
false or multiple choice, the field reveals a submenu of property options.
Click on the ellipsis (. . .) in the properties field (displayed when you click on the
field). A separate configuration dialog box appears. This is helpful for large values
that cannot be fully displayed in the parameter’s property field. Enter the property
value in the dialog box and click OK. The value now appears in the property field.
3 A description of each parameter is displayed in the Description pane when that
parameter is selected, providing an explanation of any required settings or options.
4 The Comments pane provides an area for recording notes and information about
the currently selected parameter. This is saved automatically for future referral.
5 Click OK to close the Properties Editor and save the changes.
File eWay User’s Guide
17
Sun Microsystems, Inc.
Chapter 3
Configuring the File eWay
3.2
Section 3.2
Inbound File eWay Connectivity Map Properties
Inbound File eWay Connectivity Map Properties
The inbound File eWay configuration parameters, accessed from the Connectivity Map,
are organized into the following sections:
ƒ Parameter Settings on page 18
3.2.1
Parameter Settings
The Parameter Settings section of the inbound File eWay Connectivity Map properties
contains the top level parameters displayed in Table 3.
Table 3 Inbound File eWay Connectivity Map Properties - Parameter Settings
Name
Input file
name
Description
Required Value
Specifies the file mask for input data
files.
A file mask. The default is input*.txt.
You can provide only an extension
with an asterisk (), for example, *.txt,
to allow all files with that extension.
An input file's extension is renamed
to .~in after it is picked up.
Note: If a file with the same name
as the rename name exists, for
example, input1.txt.~in, picking
up the input file fails. You must
ensure no files with the rename
names exist before the files are
processed by the inbound file
poller.
Polling
interval
The number of milliseconds the eWay
waits between poll attempts of the input
directory.
The polling interval and the MDB pool
size can be “tuned” based on the
expected volume and frequency of
incoming messages. See “Max Pool
Size” on page 23 for more information.
An integer; the acceptable range is an
integer from 2 to 99999, inclusive, and
the default is 5000 (5000 milliseconds or
5 seconds). It is not advised to enter a
value less than 5 seconds.
Caution: There is no error
message if you enter an incorrect
value.
Input type
Specifies the type of input file, for
example, bytes.
A file type. The default is Bytes, the
only valid value.
Remove EOL
Specifies whether the eWay excludes the
terminating end-of-line (EOL) characters
from records (messages) sent to a
subscriber. This property only applies if
the Multiple records per file property is
set to True.
True or False
File eWay User’s Guide
18
ƒ True enables the feature.
ƒ False disables the feature.
The default is False.
Sun Microsystems, Inc.
Chapter 3
Configuring the File eWay
Section 3.2
Inbound File eWay Connectivity Map Properties
Table 3 Inbound File eWay Connectivity Map Properties - Parameter Settings (Continued)
Name
Multiple
records per
file
Maximum
bytes per
record
Description
Required Value
Specifies whether multiple records
(messages) are obtained per file. If this
property is set to True, multiple records
(messages) are generated per line, up to
the number specified in the Maximum
bytes per record property. Any data
exceeding the maximum bytes per
record size is sent in subsequent
messages.
Specifies the maximum number of bytes
per record (message) sent to a
subscriber. This property only applies if
the Multiple records per file property is
set to True.
True or False.
ƒ True enables the feature.
ƒ False disables the feature.
The default is False.
An integer; the acceptable range is an
integer from 2 to 99999, inclusive, and
the default is 4096.
Caution: There is no error
message if you enter an incorrect
value.
Encoding
Specifies the valid encoding names. For
more information on Java encoding, refer
to the following site:
The encoding names.
http://java.sun.com/j2se/1.3/docs/api/
java/lang/package-summary.html
SerialMode
Specifies whether messages will be
handled in serial mode (one after the
other) or concurrently.
True or False.
ƒ True: indicates that messages are
handled in serial mode.
ƒ False: indicates that messages handled
concurrently.
The configured default is True.
Resend On
Error
Specifies whether inbound messages
from the input file are resent if an
exception is received after sending the
message to the Collaboration.
True or False.
ƒ True: the input file is not renamed,
messages are resent to the
Collaboration until the exception is
resolved.
ƒ False, exceptions are ignored, the
input file is renamed, and messages
are not resent to the Collaboration.
The configured default is True.
File eWay User’s Guide
19
Sun Microsystems, Inc.
Chapter 3
Configuring the File eWay
3.3
Section 3.3
Outbound File eWay Connectivity Map Properties
Outbound File eWay Connectivity Map Properties
The inbound File eWay configuration parameters, accessed from the Connectivity Map,
are organized into the following sections:
ƒ Parameter Settings on page 20
3.3.1
Parameter Settings
The Parameter Settings section of the outbound File eWay Connectivity Map
properties contains the top level parameters displayed in Table 4.
Table 4 Outbound File eWay Connectivity Map Properties - Parameter Settings
Name
Description
Required Value
Output file name
Specifies the file mask for output
data files.
An appropriate file name. The default is
output%d.dat. The %d in the file name is a
counter and increments for each new file.
Instead of %d, you can use any other
printf style that takes an integer or long
value. For
example, you can specify 1%d or %012d.
In cases where the Multiple records per
file property is set to False:
ƒ If no output file exists at the time of the
first execution, a new output file is
created for each record.
ƒ If an output file already exists at the time
of the first execution, messages are
appended to it.
Note: For more information
regarding the printf feature, see
the appropriate C language
documentation.
Add EOL
Specifies whether the system adds
an end-of-line character to each
record the eWay sends to the
output file.
True or False.
ƒ True indicates that the system will add
an EOL to each record.
ƒ False indicates otherwise.
The configured default is False.
File eWay User’s Guide
20
Sun Microsystems, Inc.
Chapter 3
Configuring the File eWay
Section 3.3
Outbound File eWay Connectivity Map Properties
Table 4 Outbound File eWay Connectivity Map Properties - Parameter Settings (Continued)
Name
Multiple records
per file
Description
Required Value
Specifies whether multiple
records (messages) can be written
to the output file. New messages
are appended to the output file.
True or False.
ƒ True indicates that the output file will
contain multiple records (messages).
ƒ False indicates that each output file
contains a single record (message).
The configured default is True.
Encoding
Specifies the valid encoding
names. For all valid encodings,
please refer to the following site:
The encoding names.
http://java.sun.com/j2se/1.3/
docs/api/java/lang/packagesummary.html
File eWay User’s Guide
21
Sun Microsystems, Inc.
Chapter 3
Configuring the File eWay
3.4
Section 3.4
File eWay Environment Properties
File eWay Environment Properties
The File eWay configuration parameters, accessed from the Environment Explorer, are
organized into the following sections:
ƒ Inbound File eWay - Parameter Settings on page 22
ƒ Inbound File eWay - MDB Settings on page 23
ƒ Outbound File eWay - Parameter Settings on page 24
3.4.1
Inbound File eWay - Parameter Settings
The Inbound File eWay - Parameter Settings section of the File eWay Environment
properties contains the top level parameters displayed in Table 5.
Table 5 File eWay Environment Properties - Inbound File eWay - Parameter Settings
Name
Directory
Description
Required Value
Specifies the folder or directory that
the eWay polls for input files.
A folder or directory name. You
must use the absolute path; specify
paths using the (forward) / slash
mark.
The configured default is C:/temp.
File eWay User’s Guide
22
Sun Microsystems, Inc.
Chapter 3
Configuring the File eWay
3.4.2
Section 3.4
File eWay Environment Properties
Inbound File eWay - MDB Settings
The Inbound File eWay - MDB Settings section of the File eWay Environment
properties contains the top level parameters displayed in Table 6.
Table 6 File eWay Environment Properties - Inbound File eWay - MDB Settings
Name
Max Pool Size
Description
Specifies the maximum number of Message
Driven Beans instantiated at any one point for
message handling.
The polling interval and the MDB pool size
(Max Pool Size) can be “tuned” based on the
expected volume and frequency of incoming
messages. A more frequent polling interval,
due to a large number of new messages, will
trigger the creation of new threads. The
number of threads that can be processed,
however, is limited by the MDB pool size.
When the maximum MDB pool limit is
reached, incoming threads are blocked.
Increasing the MDB pool size allows more
resource adapter threads to send data to the
Collaboration. In most cases, the default MDB
pool size of 1000 is sufficient.
File eWay User’s Guide
23
Required Value
An integer indicating the
maximum MDB pool size.
The default configuration is
1000.
Sun Microsystems, Inc.
Chapter 3
Configuring the File eWay
3.4.3
Section 3.4
File eWay Environment Properties
Outbound File eWay - Parameter Settings
The Outbound File eWay - Parameter Settings section of the File eWay Environment
properties contains the top level parameters displayed in Table 7.
Table 7 File eWay Environment Properties - Outbound File eWay - Parameter Settings
Name
Directory
File eWay User’s Guide
Description
Specifies the directory to which
output files are written.
24
Required Value
The absolute path and directory
name.
Sun Microsystems, Inc.
Chapter 4
Using the File eWay in a Project
This chapter provides an introduction to the File eWay components, and information
on how these components are created and implemented in a Sun Java Composite
Application Platform Suite Project.
Chapter Topics
ƒ File eWay Components on page 25
ƒ Using the File eWay with eInsight on page 26
ƒ Using the File eWay with Java-based Collaborations on page 26
4.1
File eWay Components
The File eWay is used in most of the sample Projects provided with the Sun Java™
Composite Application Platform Suite and the eWay Intelligent Adapters. The File
eWay includes the following components that are unique to this eWay:
ƒ File eWay Configuration Properties File: The properties files for the File eWay
defines how the eWay connects with external systems as well as how data
(messages) are handled. These properties are configured using the Properties
Editor. For more information about the Batch eWay properties files and the
Properties Editor see “Configuring the File eWay” on page 15.
ƒ FileClient OTD: The File OTD provides functionality for receiving or sending files
and triggering a Business Process or Collaboration. Object Type Definitions (OTDs)
map input and output message segments at the field level.
4.1.1
File OTD Operations
The following File eWay OTD attributes or operations are used in both BPEL and JCD
Projects:
ƒ receive (inbound File eWay)
ƒ write (outbound File eWay)
The write (output) Business Process operation has an additional input function
provided to receive and handle incoming error exception messages. For more
information on this feature, see the Sun SeeBeyond eInsight Business Process Manager
User’s Guide.
File eWay User’s Guide
25
Sun Microsystems, Inc.
Chapter 4
Using the File eWay in a Project
4.2
Section 4.2
Using the File eWay with eInsight
Using the File eWay with eInsight
eGate components can be deployed as Activities in eInsight Business Processes. Once a
component is associated with an Activity, eInsight invokes it using a Web Services
interface. eGate components that can interface with eInsight in this way include the
following:
ƒ Object Type Definitions (OTDs)
ƒ eWays
ƒ Collaborations
Using the Enterprise Designer and eInsight, you can add an Activity to a Business
Process, then associate that Activity with an eGate component, for example, an eWay.
Then, when eInsight runs the Business Process, it automatically invokes that
component via its Web Services interface.
You can add File eWay objects to an eInsight Business Process during the system design
phase. To make this association, select the desired receive or write operation from the
Project Explorer under Sun SeeBeyond > eWays > File > FileClient and drag it into the
eInsight Business Process canvas (GUI). Once you have associated the desired
component with a Business Process, the eInsight engine can automatically invoke that
component during run time, using a Business Process Execution Language (BPEL)
interface.
See the eInsight Business Process Manager User’s Guide for details.
4.3
Using the File eWay with Java-based Collaborations
Java-based Collaboration Definitions contain a set of Business Rules that define the
processing and transport of data (messages) through the Sun Java™ Composite
Application Platform Suite Projects.
You create Java Collaboration Definitions using the Collaboration Definition Wizard
(Java) to assign the appropriate Object Type Definitions (OTDs) and Web Service
operations to your Collaboration.
Once you have created the Collaboration Definition, you use the Collaboration Editor
(Java) to create the business logic of the Collaboration, assigning input and output data
relationships using the Collaboration Editor’s Business Rules Designer.
The File eWay Intelligent Adapter OTD provides a number of Java Methods that allow
you to add file (input/output) business logic to your Collaboration Business Rules. For
more information on the Java methods provided with the File OTD, see the File eWay
Javadoc (see “File eWay Javadoc” on page 7).
For more information on how to use the File eWay with Java-based Collaboration
Definitions, see the Sun SeeBeyond eGate™ Integrator User’s Guide.
File eWay User’s Guide
26
Sun Microsystems, Inc.
Index
properties
Connectivity Map 16
Connectivity Map properties
modifying 16
Environment 16
Environment properties
modifying 16
Properties Editor 17
modifying properties 17
Index
B
R
Business Process Execution Language (BPEL) 26
Remove EOL 18
C
Connectivity Map
properties 16
conventions, text 7
S
E
T
eInsight with File eWay
overview 26
Environment
properties 16
External Application
creating 15
text conventions 7
supported operating systems 9
I
Input file name 18, 20
Input type 18
J
Javadoc 7
M
Maximum bytes per record 19
Multiple records per file 19
O
operating systems
requirements 9
supported 9
P
platforms
requirements 9
supported 9
Polling interval 18
File eWay User’s Guide
27
Sun Microsystems, Inc.