The j2eetm tutorial - phần 9 ppt

281 J2EE™Connector Technology by Dale Green and Beth Stearns THE other chapters in this book are intended for business application develop- ers, but this chapter is for advanced users such as system integrators and tools developers. The examples in this chapter demonstrate the J2EE™ Connector Technology by accessing relational databases. However, this technology is not a substitute for the JDBC API. Business application developers should continue to use the JDBC™ API to access relational databases. The J2EE Connector Technology enables J2EE components such as enterprise beans to interact with Enterprise Information Systems (EIS). EIS software includes various types of systems: Enterprise Resource Planning (ERP), main- frame transaction processing, non-relational database, among others. The J2EE Connector Technology simplifies the integration of diverse EIS systems. Each EIS requires just one implementation of the J2EE Connector Technology. Because an implementation adheres to the J2EE Connector Specification,itis portable across all compliant J2EE servers. About Resource Adapters 284 Resource Adapter Contracts 284 Administering Resource Adapters 285 The Black Box Resource Adapters 287 Transaction Levels 287 Properties 288 Configuring JDBC™ Drivers 289 Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 282 J2EE™CONNECTOR TECHNOLOGY Resource Adapter Tutorial 290 Setting Up 290 Deploying the Resource Adapter 290 Testing the Resource Adapter 291 Common Client Interface (CCI) 293 Overview of the CCI 293 Programming with the CCI 295 Writing a CCI Client 304 CCI Tutorial 304 About Resource Adapters A resource adapter is a J2EE component that implements the J2EE Connector Technology for a specific EIS. It is through the resource adapter that a J2EE application communicates with an EIS. (See Figure 20.) Stored in a RAR (Resource adapter ARchive) file, a resource adapter may be deployed on any J2EE server, much like the EAR file of a J2EE application. A RAR file may be contained in a EAR file or it may exist as a separate file. A resource adapter is analagous to a JDBC driver. Both provide a standard API through which an application can access a resource that is outside of the J2EE server. For a resource adapter, the outside resource is an EIS; for a JDBC driver, it is a DBMS. Resource adapters and JDBC drivers are rarely created by applica- tion developers. In most cases, both types of software are built by vendors who sell products such as tools, servers, or integration software. Resource Adapter Contracts Figure 20 shows the two types of contracts implemented by a resource adapter. The application contract defines the API through which a J2EE component such as an enterprise bean accesses the EIS. This API is the only view that the compo- nent has of the EIS. The resource adapter itself and its system contracts are trans- parent to the J2EE component. The system contracts link the resource adapter to important services—connec- tion, transaction, and security—that are managed by the J2EE server. The connection management contract supports connection pooling, a technique that enhances application performance and scalability. Connection pooling is transparent to the application, which simply obtains a connection to the EIS. Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com ABOUT RESOURCE ADAPTERS 283 Because of the transaction management contract, calls to the EIS may be enclosed in a XA transactions. XA transactions are global—they may contain calls to multiple EISs, databases, and enterprise bean business methods. Although often appropriate, XA transactions are not mandatory. Instead, an application may use local transactions, which are managed by the individual EIS, or it may use no transactions at all. To protect the information in an EIS, the security management contract provides these mechanisms: authentication, authorization, and secure communication between the J2EE server and the EIS. Figure 20 Accessing an EIS Through a Resource Adapter Administering Resource Adapters Installing a resource adapter is a two-step process: 1. Deploy the RAR file containing the resource adapter onto a server. J2EE Server Enterprise Bean EIS Resource Adapter Web Component Transaction Connection Security Managers: System Contracts Application Contract Application Contract Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 284 J2EE™CONNECTOR TECHNOLOGY The following command, for example, deploys a sample black box resource adapter onto the local host. (For Windows, in the following commands omit the backslash character, change $J2EE_HOME to %J2EE_HOME%, and enter the entire command on a single line.) deploytool -deployConnector \ $J2EE_HOME/lib/connector/cciblackbox-tx.rar \ localhost 2. Add a connection factory for the resource adapter. Suppose that you wanted to add a connection factory for the resource adapter in the cciblackbox-tx.rar file. The JNDI name of the connection factory will be eis/MyCciBlackBoxTx. To override the default value of the property named ConnnectionURL, you specify the URL of a database. (A property is a name-value pair used to configure a connection factory.) To add the connection factory, you might enter the following j2eeadmin command: j2eeadmin -addConnectorFactory \ eis/MyCciBlackBoxTx \ cciblackbox-tx.rar \ -props \ ConnectionURL=jdbc:oracle:thin:@myhost:1521:ACCTDB For the full syntax of the deploytool and j2eeadmin commands, see J2EE™SDK Tools (page 309). These commands also list and remove resource adapters and connection factories. To list the resource adapters that have been deployed: deploytool -listConnectors localhost To list the connection factories that have been added: j2eeadmin -listConnectorFactory To uninstall the resource adapter deployed in step 1: deploytool -undeployConnector \ $J2EE_HOME/lib/connector/cciblackbox-tx.rar \ localhost To remove the connection factory added in step 2: j2eeadmin -removeConnectorFactory eis/MyCciBlackBoxTx Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com THE BLACK BOX RESOURCE ADAPTERS 285 The Black Box Resource Adapters The J2EE SDK includes several black box resource adapters for performing end- to-end and compatibility testing. The underlying EIS of these adapters is a rela- tional DBMS. The client API is the JDBC 2.0 API and the javax.sql.Data- Source interface. Underneath, the black box adapters use JDBC drivers to communicate with relational databases. For more information, see Configuring JDBC™ Drivers (page 287). Note: Although the black box adapters use JDBC, resource adapters are not meant to replace JDBC for accessing relational databases. The black box adapters are for testing purposes only. Because they use JDBC, they can be plugged into existing tests that also use JDBC. Transaction Levels The black box resource adapters reside in the $J2EE_HOME/lib/connector (Unix) or %J2EE_HOME%\lib\connector (Windows) subdirectory. The follow- ing table lists the blackbox RAR files and the different transaction levels that they support: For the XA_TRANSACTION level, the underlying JDBC driver must support the XA requirements as defined by the JDBC 2.0 API. Table 33 Black Box Transaction Levels File Transaction Level blackbox-notx.rar NO_TRANSACTION blackbox-tx.rar LOCAL_TRANSACTION blackbox-xa.rar XA_TRANSACTION cciblackbox-tx.rar LOCAL_TRANSACTION cciblackbox-xa.rar XA_TRANSACTION Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 286 J2EE™CONNECTOR TECHNOLOGY Properties A resource adapter may contain properties, name-value pairs containing infor- mation specific to the resource adapter and its underlying EIS. These properties are defined in the deployment descriptor of each blackbox RAR file. Because the EIS of a blackbox adapter is a relational database, the properties contain infor- mation required for connecting to a database. The following table lists the prop- erties of the black box adapter files. The next table shows the default values for the black box properties. To override a default property value, you set the value when adding a connection factory with the j2eeadmin command. See the section, Administering Resource Adapters (page 283). Table 34 Black Box Properties File Property Name Description blackbox-notx.rar ConnectionURL URL of database blackbox-tx.rar ConnectionURL URL of database blackbox-xa.rar XADataSourceName JNDI name of XADataSource cciblackbox-tx.rar ConnectionURL URL of database cciblackbox-xa.rar XADataSourceName JNDI name of XADataSource Table 35 Default Values for Black Box Properties Property Name Description ConnectionURL jdbc:cloudscape:rmi:CloudscapeDB;create=true XADataSourceName jdbc/XACloudscape_xa Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com THE BLACK BOX RESOURCE ADAPTERS 287 Configuring JDBC™ Drivers If you are running the black box adapters against a Cloudscape database, you may skip this section. If you are using a database other than Cloudscape, you should perform the steps that follow. The Non-XA Black Box Adapters 1. Set the JDBC driver class. Use the j2eeadmin tool with the -addJdb- cDriver option and specify the driver class name. The syntax for this option is: j2eeadmin -addJdbcDriver <class name> 2. Edit the bin/userconfig.sh (UNIX) or bin\userconfig.bat (Win- dows) file, setting the J2EE_CLASSPTH variable to the location of the JDBC driver classes. 3. Restart the J2EE server. The XA Black Box Adapters 1. Set the XADatasource property. With the j2eeadmin tool and the addJd- bcXADatasource option, specify the JNDI name and class name for the XADatasource property. Optionally, you may specify the XA user name and password and you may override the default property value. The syntax follows: j2eeadmin -addJdbcXADatasource <jndi name> <class name> [<xa user name> <xa password>] [-props (<name>=<value>)+] The preceding command results in two data sources. One is a DataSource object with the specified JNDI name from which the J2EE application gets a Connection instance. The other is an XADatasource object whose JNDI name is the <jndi-name> parameter appended with two underscores and xa (<jndi-name>__xa). Behind the scenes, the DataSource uses the XADataSource to create connections. 2. Restart the J2EE server. Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 288 J2EE™CONNECTOR TECHNOLOGY Resource Adapter Tutorial This tutorial shows you how to deploy the black box resource adapter stored in the blackbox-tx.rar file. To test the resource adapter, you will modify the examples/src/ejb/account/AccountEJB.java file so that it accesses the Cloudscape database through the resource adapter. The AccountEJB.java file is also used in another example. For more information, see Tips for Running the AccountEJB Example (page 94) Setting Up 1. Start the J2EE server. j2ee -verbose 2. In another terminal window, set the J2EE_HOME environment variable to the directory in which you’ve installed this release. 3. Follow the instructions in the section, Setting Up the Database (page 94). Deploying the Resource Adapter 1. Deploy a black box resource adapter that is packaged in the blackbox- tx.rar file. UNIX: deploytool -deployConnector \ $J2EE_HOME/lib/connector/blackbox-tx.rar localhost Windows: (Enter the following command on a single line.) deploytool -deployConnector %J2EE_HOME%\lib\connector\blackbox-tx.rar localhost 2. Add a connection factory for the resource adapter. The JNDI name for the connection factory is eis/MyBlackBoxTx. UNIX: j2eeadmin -addConnectorFactory \ eis/MyBlackBoxTx blackbox-tx.rar Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com RESOURCE ADAPTER TUTORIAL 289 Windows: (Enter the following command on a single line.) j2eeadmin -addConnectorFactory eis/MyBlackBoxTx blackbox-tx.rar 3. Verify that the resource adapter has been deployed. deploytool -listConnectors localhost The deploytool displays these lines: Installed connector(s): Connector Name: blackbox-tx.rar Installed connection factories: Connection Factory JNDI Name: eis/MyBlackBoxTx Testing the Resource Adapter 1. If you are new to the J2EE SDK, you may want to review the instructions in Getting Started (page 43). 2. Locate the AccountEJB.java source code, which resides in the exam- ples/src/ejb/account directory. 3. Edit the AccountEJB.java source code, changing the value assigned to the dbName variable as follows: private String dbName = “java:comp/env/MyEIS”; 4. Compile the source code in the account directory: a. Go to examples/src. b. Type ant account. 5. Run the New Enterprise Bean Wizard of the deploytool by selecting File- > New Enterprise Bean. Although the wizard displays many dialog boxes, for this example only the following dialog boxes require input. 6. General Dialog Box c. Select the Entity radio button. d. In the Enterprise Bean Name field, enter AccountBean. Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 290 J2EE™CONNECTOR TECHNOLOGY 7. Entity Settings Dialog Box a. Select the radio button for bean-managed persistence. 8. Resource References Dialog Box: a. Click Add. b. Enter the values specified in the following table. The eis/MyBlackBoxTx JNDI name matches the name of the connection factory that you added in step 2 of Deploying the Resource Adapter (page 288). The MyEIS value of the Coded Name field corre- sponds to this line in the AccountEJB.java source code: private String dbName = “java:comp/env/MyEIS”; Although it is included in the source code, the java:comp/env/ subcon- text is implicit in the Coded Name field of the Resource References dialog box. 9. Transaction Management Dialog Box: a. For the business methods, in the Transaction Type column select Required. The business methods are debit, credit, getFirstName, getLastName, and getBalance. 10.Exit the wizard by clicking Finish. 11.Create a J2EE application client. a. Select New->Application Client b. Name the client AccountClient. c. Add the ejb/SimpleAccount enterprise bean reference. Table 36 Resource References Values Field Value Coded Name MyEIS Type javax.sql.DataSource Authentication Container JNDI Name eis/MyBlackBoxTx Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com [...]... -addJdbcDriver Adds the JDBC driver specified by its fully-qualified You must also update the J2EE_CLASSPATH environment variable in the file bin\userconfig.bat Then you must restart the J2EE server -addJdbcDatasource Adds the JDBC DataSource with the specified and -addJdbcXADatasource [ ] [-props (=)+]... name-value pairs -list Lists resources of the specified , either: ConnectorFactory, JdbcDriver, JdbcDatasource, JdbcXADatasource, JmsDestination, or JmsFactory There is no space between -list and -remove Removes the resource of the specified and (See the description of -list for the allowed ... Option Description -addConnectorFactory [:] [ ] [-props (=)+] Adds a connection factory with the specified The connection factory is contained in the RAR file specified by The must be the base name of the file; it cannot include any prefix ending in / (Unix) or \ (Windows) If the RAR file is... on the J2EE server running on the machine specified by -listConnectors Lists the resource adapters that are deployed on the J2EE server running on the machine specified by -undeployConnector Undeploys the resource adapter contained in the file specified by from the J2EE server running on the machine specified by ... COM.cloudscape.core.JDBCDriver registered in DriverManager Mon Aug 09 11:50:30 PDT 199 9: [RmiJdbc] Binding Mon Aug 09 11:50:30 PDT 199 9: [RmiJdbc] No installation of RMI Security Manager Mon Aug 09 11:50:31 PDT 199 9: [RmiJdbc] RmiJdbcServer bound in rmi registry To stop the server type the following command: cloudscape -stop You should see output similar to the following: Attempting to shutdown RmiJdbc server... • • GET - retrieves the resource identified by the request URL HEAD - returns the headers identified by the request URL POST - sends data of unlimited length to the web server PUT - stores a resource under the request URL DELETE - removes the resource identified by the request URL 307 Simpo PDF Merge and Split Unregistered Version - http://www.simpopdf.com 308 HTTP OVERVIEW • OPTIONS - returns the HTTP... running on the machine specified by Optionally, a JAR file for a stand-alone Java application client may be created by specifying -deployConnector Deploys the resource adapter contained in the RAR file specified by onto the J2EE server running on the machine specified by -listApps Lists the J2EE applications... (=)+] Adds the JDBC XADataSource with the specified and fully-qualified Optionally, a user name and password for the DataSource may be specified Also optional is the -props flag, followed by one or more name-value pairs that specify properties for this DataSource -addJmsDestination (queue|topic) Adds a JMS destination with the specified and declares the destination... MyCoffee Test the Resource Adapter 1 In a terminal window, set the APPCPATH environment variable to the name of the stub client JAR file (CoffeeAppClient.jar) 2 Go to the directory containing the application EAR file 3 Run the application with the runclient script In the following example, the application EAR file is CoffeeApp.ear and the name of the J2EE application client is CoffeeClient: runclient -client... with the user and password values obtained by the setSessionContext method The CciConnectionSpec class is the implementation of the ConnectionSpec interface 2 Call the ConnectionFactory.getConnection method to obtain a connection to the database (The reference to the ConnectionFactory was obtained in the setSessionContext method.) Use the CciConnectionSpec object to pass the required properties to the . Adapter Tutorial 290 Setting Up 290 Deploying the Resource Adapter 290 Testing the Resource Adapter 291 Common Client Interface (CCI) 293 Overview of the CCI 293 Programming with the CCI 295 Writing. using a database other than Cloudscape, you should perform the steps that follow. The Non-XA Black Box Adapters 1. Set the JDBC driver class. Use the j2eeadmin tool with the -addJdb- cDriver option. subdirectory. The follow- ing table lists the blackbox RAR files and the different transaction levels that they support: For the XA_TRANSACTION level, the underlying JDBC driver must support the XA requirements