Attunity Connect and BEA WebLogic (Version 8.1)

Attunity Connect and BEA WebLogic (Version 8.1)

Attunity Connect and BEA WebLogic (Version 8.1) 2006 by Attunity Ltd. Due to a policy of continuous development, Attunity Ltd. reserves the right to alter, without prior notice, the specifications and descriptions outlined in this document. No part of this document shall be deemed to be part of any contract or warranty whatsoever. Attunity Ltd. retains the sole proprietary rights to all information contained in this document. No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopy, recording, or otherwise, without prior written permission of Attunity Ltd. or its duly appointed authorized representatives. Product names mentioned in this document are for identification purposes only and may be trademarks or registered trademarks of their respective companies.

Table of Contents About this Manual 5 Chapter 1: Installing the Attunity Legacy Adapter 9 Troubleshooting the Configuration... 9 Multiple Connections for the Attunity Legacy Adapter... 10 Chapter 2: Using the Attunity Legacy Adapter 11 Defining the Attunity Legacy Adapter to WebLogic... 11 Including Services in an Application View...16 Including Events in an Application View...21 Notes When Using the Attunity Legacy Adapter... 25 Supported Data Types...26 Known Restrictions... 26 Chapter 3: Accessing Data Using via JDBC 27 Setting Up the Attunity Connect JDBC Driver... 27 Setting Up WebLogic...28 Testing the Attunity Connect JDBC Driver With WebLogic... 29

iv Attunity Connect and BEA WebLogic (Version 8.1)

About this Manual Attunity Connect is an information infrastructure solution that provides built-in connectivity to data sources and applications across a distributed environment that can encompass different platforms, networks, and even the Internet. In addition to a range of ready-to-use drivers, adapters and integration software, Attunity Connect includes development and management tools that make it easy to add applications and data sources to the integrated enterprise. Attunity Connect provides an adapter for BEA WebLogic Integration, the Attunity Legacy Adapter, enabling enterprises to unite applications and data from more than 30 data sources on more than 20 computing platforms, including OS/390, OS/400, Compaq NonStop, OpenVMS, UNIX and Windows using J2EE Connector Architecture (JCA). The Attunity Legacy Adapter provides a JCA frontend to unite applications and data. You can also use the Attunity Connect JDBC driver, to connect to Attunity Connect from BEA WebLogic to access data sources on platforms supported by Attunity Connect. Intended Audience Related Information This manual is intended for users of BEA WebLogic who are using the Attunity Legacy Adapter to extend their use of WebLogic to access additional data sources and applications supported by Attunity Connect. This manual assumes you are familiar with whichever of the following you use to access data: Sun s JDBC data access specification The Microsoft ODBC data access specification The Microsoft ActiveX Data Objects (ADO) specification Standard ANSI 92 SQL Sun s J2EE Connector Architecture (JCA) XML

5 Attunity Connect and BEA WebLogic (Version 8.1) Typographic Conventions Conventions for Commands Related Documentation This document uses the following typographic conventions: Italics XTo do Sample code Xyz Platforms Italics denotes either a placeholder/variable for an actual value or a new term. A bolded sentence starting with the word To is followed by a procedure. This symbol prefaces a note to the main text. This font denotes sample code and commands that you type on the keyboard. Grey shading highlights platform-specific information within a topic. The following conventions are used to describe commands entered to the keyboard or console: Keywords are shown in standard type. Variables are shown as italics. Square brackets ([]) enclose optional items. Vertical lines ( ) separate between choices. Ellipses (...) indicate that the preceding item can be repeated. BEA WebLogic can run on a machine without Attunity Connect. However the target data source or application must reside on a platform where Attunity Connect exists and be configured within Attunity Connect. The Attunity Connect documentation set includes the following: Attunity Connect Release Notes Getting Started with Attunity Connect Attunity Connect Installation Guides Attunity Connect Reference Attunity Connect Guide Attunity Connect and Applications New features for the current Attunity Connect version. A walk-through describing how to connect to data using Attunity Connect. Guides describing how to install Attunity Connect on HP (Compaq) NonStop, OpenVMS, OS/390 and Z/OS, OS/400, UNIX and Windows platforms. A complete reference to Attunity Connect. A guide to using Attunity Connect application adapters and data sources on all platforms. Tutorials demonstrating how to use Attunity Connect with various applications, such as IBM WebSphere.

Using the Attunity Connect Syntax File (NAV.SYN) Attunity Connect Developer SDK Documentation detailing how to use the Attunity Connect syntax file to control the way SQL is processed by Attunity Connect. Documentation detailing the Attunity Connect SDK, which enables you to build application adapters and data adapters. In addition, you can define custom data types and start-up functions.

7 Attunity Connect and BEA WebLogic (Version 8.1)

Chapter 1 Installing the Attunity Legacy Adapter The Attunity Legacy Adapter is provided in a zip file: Windows platforms: attunitylegacyadapterforbeav8.zip UNIX platforms: attunitylegacyadapterforbeav8.tar Versions of the Attunity Legacy Adapter are also available on request for BEA WebLogic versions 7 and 2.1. X To install the Attunity Legacy Adapter: The following procedure is based on WebLogic running under Windows. The procedure is similar for UNIX. 1. Copy the file ATTUNITY_LEGACY_ADAPTER.ear from the zip file to the applications directory for the WebLogic server you want to run. For example, when using the samples server, copy the file to the following directory: bea_home_directory\samples\domains\integration\applications 2. Start the relevant WebLogic server. Start the WebLogic server whose configuration was changed for the Attunity Legacy Adapter. WebLogic compiles all new modules, prolonging the start up time. Troubleshooting the Configuration If you have a problem with the configuration, check that the definitions have been specified in the relevant config.xml file. For example, if you installed the Attunity Legacy Adapter for use with the Samples server, check the config.xml file in the bea_home_directory\weblogic81\samples\domains\integration. The following entry should be included in the config.xml file:... <Application Deployed="true" Name="_appsdir_ATTUNITY_LEGACY_ADAPTER_ear" Path="bea_wl_home\samples\domains\integration\applications\ ATTUNITY_LEGACY_ADAPTER.ear" StagedTargets="cgServer" StagingMode="stage" TwoPhase="true"> <ConnectorComponent Name="ATTUNITY_LEGACY_ADAPTER" Targets="cgServer" URI="ATTUNITY_LEGACY_ADAPTER.rar"/>

9 Attunity Connect and BEA WebLogic (Version 8.1) <WebAppComponent Name="ATTUNITY_LEGACY_ADAPTER_Web.war" Targets="cgServer" URI="ATTUNITY_LEGACY_ADAPTER_Web.war"/> </Application>... where bea_wl_home is the directory where WebLogic Integration is installed. For example, c:\bea\weblogic81. Multiple Connections for the Attunity Legacy Adapter The WebLogic Application Integration Max Capacity property should be set to a meaningful value for the Attunity Legacy Adapter (such as 1000, enabling 1000 connections to be created). To check the current value, do the following: 1. Enter the WebLogic Server Console at the following URL: http://localhost:7001/console If prompted for a username and password, enter a valid username and password for BEA WebLogic. 2. In the Console tree on the left of the screen, click ATTUNITY_LEGACY_ADAPTER, under Integration/Deployments/Applications/_appsdir_ATTUNITY_LEG ACY_ADAPTER_ear. 3. Click the Descriptor tab in the right window. 4. Click weblogic-ra.xml file. 5. In the XML that is displayed, check the max-capacity value: <pool-params> <initial-capacity>0</initial-capacity> <max-capacity>1000</max-capacity> <capacity-increment>1</capacity-increment>... </pool-params>

Chapter 2 Using the Attunity Legacy Adapter The Attunity Legacy Adapter provides access to any application adapter or data source defined in Attunity Connect. This guide assumes that the setup of the applications and data sources in Attunity Connect has been completed. For details about setting up applications and data sources in Attunity Connect, refer to Attunity Connect Reference and Attunity Connect Guide. Defining the Attunity Legacy Adapter to WebLogic After starting the WebLogic server, use http://localhost:serverport/wlai to access the WebLogic Application Integration application. The default is http://localhost:7001/wlai. 1. Logon, with a valid WebLogic username and password. The Select Application screen is displayed. 2. Select an application. For example, use the deployed sampleapp application. The sampleapp application is installed with the WebLogic installation.

11 Attunity Connect and BEA WebLogic (Version 8.1) 3. Click OK. The following screen is displayed: 4. To add a new application view, click Add Application View. You can remove an undeployed application view (where status is Not Testing) or modify a non-deployed application view by clicking the view.

Chapter 2 Using the Attunity Legacy Adapter 12 5. The Define New Adapter screen is displayed. 6. Enter an name for the Application View and select ATTUNITY_LEGACY_ADAPTER as the Associated Adapter. 7. Click Create New Connection at the bottom of the screen.

13 Attunity Connect and BEA WebLogic (Version 8.1) The following screen is displayed: 8. Click Define.

Chapter 2 Using the Attunity Legacy Adapter 14 9. In the Configuration Connection Parameters screen enter the connection details as described below: Where: Attunity Server Host Name The name or address of the machine where the Attunity Connect daemon is running. If the adapter to be accessed is defined in the binding configuration on the local machine, the daemon must be running on this machine. In this case you can specify localhost as the host name. Adapter Name The name of the adapter. You can use any adapter that has been defined in the binding used with the specified workspace (or the default Navigator workspace if the Workspace field is left empty). The remaining fields default to the Attunity Connect defaults if unspecified (port 2551, Navigator workspace and anonymous access to the workspace). When specifying an event, you must enter the name of the event workspace, instead of using the default Navigator workspace. For details of events, see "Including Events in an Application View" on page 20. 10. Click Continue. 11. The Create New Browsing Connection screen is redisplayed. Scroll to the bottom of the screen and click OK.

15 Attunity Connect and BEA WebLogic (Version 8.1) 12. The following screen is displayed: You use this screen to add events and services to the application view. Including Services in an Application View The following section describes how to build a WebLogic application view with services. A service is specified in Attunity Connect as an interaction defined for an application adapter. In this example, the calc adapter sample, supplied with Attunity Connect is used. For details about how to set up this sample, refer to the readme file in NAVROOT\Samples\Adapters\calc where NAVROOT is the directory where Attunity Connect is installed.

Chapter 2 Using the Attunity Legacy Adapter 16 X To add a service to the application view: 1. In the Services area, click Add. The following screen is displayed: 2. Enter a unique name to identify the service. This name is used within WebLogic to identify the service and does not have to match either the adapter name or the interaction name. 3. Select the interaction from the list of interactions available for the adapter. This list of interactions is dependent of the adapter used. 4. Click Add.

17 Attunity Connect and BEA WebLogic (Version 8.1) The Administration screen is redisplayed. 5. Click Test to save and deploy the service.

Chapter 2 Using the Attunity Legacy Adapter 18 The following screen is displayed: To edit the application view in order to add new services or events, the application view cannot be deployed. Click Stop Testing to undeploy the application view to enable it to be edited. The contents of a service (such as the SQL in a SELECT statement) cannot be edited. The configuration of the application view can be edited and services can be removed and new services added. 6. The services in the application view can be tested individually by clicking Test for each service.

19 Attunity Connect and BEA WebLogic (Version 8.1) Testing a Service In the Summary screen, click Test (click the Test link that relates to the specific service you want to test). The Test Service screen is displayed. Edit the XML to contain meaningful parameters to test. Click Test to display the results of the service after it is executed. The results show the input and the output in XML format.

Chapter 2 Using the Attunity Legacy Adapter 20 Including Events in an Application View The following section describes how to build a WebLogic application view with events. An event in Attunity Connect is defined as an interaction defined for an event adapter. In this example, the bigordersevent adapter sample, supplied with Attunity Connect is used. For details about how to set up this sample, refer to the readme file in NAVROOT\Samples\Adapters\Ordersys where NAVROOT is the directory where Attunity Connect is installed. X To set up access to an event adapter: 1. In the WebLogic Define New Application View screen, supply a name for the adapter and select Attunity Legacy Adapter as the Associated Adapter. 2. Click OK. The Configure Connection Parameters screen is displayed: 3. Enter the following parameters: Attunity Server Host Name Enter the name or address of the machine where the Attunity Connect daemon is running. If the adapter to be accessed is defined in the binding configuration on the local machine, the daemon must be running on this machine. In this case you can specify localhost as the host name.

21 Attunity Connect and BEA WebLogic (Version 8.1) Workspace Enter the name of the workspace under which the adapter is defined in the binding configuration. The workspace used in this example is called events. The workspace used with an event is usually not the default Navigator workspace. Adapter Name Enter the name of the adapter as defined in the binding configuration used with the specified workspace. In this example, the adapter is called "OrdersQueue". The adapter name is case-sensitive. Log Level Select the level of logging to use for the event. X To add an event to the application view: 1. In the Application View screen, click Add in the Events area to add an event to the application view.

Chapter 2 Using the Attunity Legacy Adapter 22 The following screen is displayed: 2. Enter a unique name to identify the event. 3. Select the event from the list of events available.

23 Attunity Connect and BEA WebLogic (Version 8.1) 4. Click Add. You return to the Application View screen. 5. Click Select/Edit. The Connection Information screen is displayed.

Chapter 2 Using the Attunity Legacy Adapter 24 6. Click Select Existing under Event Connection. The Select Event Connection screen is displayed. 7. Select the connection for the event and click OK. You return to Connection Information screen. 8. To edit the connection settings such as pooling size information, click Event under Event Connection, otherwise proceed to step 17. 9. Click Define. Edit the connection parameters in the Configure Event Delivery Parameters screen. 10. Click Continue to return to the Edit Event Connection screen. 11. Click OK. 12. Click Back. You return to Application View screen. 13. Click Test to deploy the event. A Summary is displayed. 14. Click Test in the event area of the specific event, to test the event. You can test the event in one of the following ways: Run a predefined service to trigger the event. Wait for a service to be run from another application. 15. Specify the amount of time to wait before timing out. For example, specify 20000 milliseconds (the recommended minimum). 16. Click Test to display the results. Notes When Using the Attunity Legacy Adapter An application view cannot be changed when it is deployed. In order to change an application or add services to it, the application view must first be undeployed: access the Application View Console (using the link on the top part of the screen) and access the relevant view. Click Undeploy in the Summary for Application View screen. Services which require parameter input can be defined with predefined values for testing or with values that are entered immediately prior to testing the service.

25 Attunity Connect and BEA WebLogic (Version 8.1) Supported Data Types The following are valid data types: BIGINT DATE DOUBLE INTEGER NUMERIC SMALLINT TIMESTAMP VARCHAR CHAR DECIMAL FLOAT LONGVARCHAR REAL TIME TINYINT Known Restrictions The following are some of common errors and their solutions: Adapter names are case-sensitive. The case used in the binding configuration must be used in WebLogic. It is recommended that the daemon server mode is set multiclient. Thus, if a workspace other than the default Navigator workspace is used, it is recommended that it is configured as multiclient.

Chapter 3 Accessing Data Using JDBC WebLogic enables access to data sources via JDBC. Using the Attunity Connect JDBC driver, you can connect to any data source defined in Attunity Connect. WebLogic can have multiple server directories on the same installation, each with its own configuration. The following procedures are based on the examples server. Setting Up the Attunity Connect JDBC Driver To configure WebLogic, modify the environment and server startup files to include the Attunity Connect JDBC driver definitions in the WebLogic CLASSPATH. For example, when using the examples server, modify the following command files: beawl_home\samples\domains\examples\setexamplesenv.cmd beawl_home\samples\domains\examples\startexamplesserver.cmd where beawl_home is the root of the BEA WebLogic installation. setexamplesenv.cmd sets up all the required environment variables. startexamplesserver.cmd sets up all the required environment variables for WebLogic and starts the server with the example settings. Make the following addition to these command files:... set CLASSPATH=...;navroot\java\nvjdbc2.jar... where navroot is the root of the Attunity Connect installation. If you specify a path with spaces in the path (for example c:\program Files\...), surround the path with double quotes ("). as in the following example: "c:\program Files\Attunity\Connect\java\nvjdbc2.jar". For debugging and tracing the following can also be added to the CLASSPATH: "navroot\java\nvlog2.jar";"navroot\java\nvapispy2.jar" Run these command files.

28 Attunity Connect and BEA WebLogic (Version 8.1) Setting Up WebLogic After starting the WebLogic server, use http://localhost:serverport/console to access the WebLogic Server Administration Console. The default is http://localhost:7001/console. 1. Logon, with a valid WebLogic username and password. 2. Configure a new Connection Pool. In the explorer pane do the following: a) Drill-down the tree as follows: Integration -> Services -> JDBC -> Connection Pools. b) Right-click Connection Pools and select Configure a new JDBCConnectionPool. The Choose database panel is displayed. c) Choose Other for the Database Type value and click Continue. The Define and test connection panel is displayed. d) Enter the following: Name The name you want to call the connection pool (for example, AttunityConnectPool). Driver Classname The Attunity Connect JDBC driver. This value must be: com.attunity.jdbc.nvdriver URL The Attunity Connect JDBC connect string. Use the following string, where datanase_name is the name of a data source defined in the Attunity Connect NAV binding: jdbc:attconnect://localhost:2551;deftdpname=dat abase_name;qualifyowner=1;onetdpmode=1; Refer to Attunity Connect Thin Client documentation for details of all the connect string parameters. Leave the Database User Name and Password values blank and click Continue. e) If there is only one server running, click Create and deploy. Otherwise, click Save configuration and in the Target and deploy tab select the server you are working with (the default server is cgserver) and click Apply. 3. Configure the data source in WebLogic. In the explorer pane do the following: a) Drill-down the tree as follows: Integration -> Services -> JDBC -> Data Sources. b) Right-click Data Sources and select Configure a new JDBCTxDataSource. The Choose database panel is displayed.

Chapter 3 Accessing Data Using JDBC 29 c) Choose Other for the Database Type value and click Continue. The Configure the data source panel is displayed. d) Enter the following: Name The name you want to call the data source (for example, AttunityDS). JNDI Name Enter the name used for the data source name (for example, AttunityDS). Click Continue. The Connect to connection pool panel is displayed. e) Select the connection pool you defined above. f) Click Continue. The Target the data source panel is displayed. g) Select the server you are working with (the default server is cgserver) and click Create. Testing the Attunity Connect JDBC Driver With WebLogic After setting up the database connection as described above, modify the weblogic-ejb-jar.xml file in the beanmanaged example. The beanmanaged example is located in the following directory: beawl_home\samples\server\examples\src\examples\ejb20\basic\be anmanaged where beawl_home is the root of the BEA WebLogic installation. Modify this file as follows: 1. In the <jndi-name> line change the data source name from examples-datasource-demopool to the name of the data source defined in "Testing the Attunity Connect JDBC Driver With WebLogic" on page 29 (for example, AttunityDS). 2. Run the following command file to setup the environment to recompile the sample: beawl_home\samples\domains\examples\setexamplesenv.cmd 3. Recompile the sample (using ant). 4. Run the modified sample, as follows: > java examples.ejb20.basic.beanmanaged.client t3://localhost:7001

30 Attunity Connect and BEA WebLogic (Version 8.1)