Have your application call my application, Part 3: The resource adapter Geronimo message-driven beans, JCA resource adapters, and e-mail Skill Level: Intermediate Madhuri Suda ([email protected]) Java programmer Freelance 05 Sep 2006 In Part 1 and Part 2 of this three-part tutorial series, you learned how to develop message-driven beans (MDBs) and entity beans and deploy and test them in Apache Geronimo and how to create an e-mail application and deploy it in Java™ Apache Mail Enterprise Server (Apache James). In this final installment, you'll tie the application together by learning all about Java 2 Platform, Enterprise Edition (J2EE) Connector Architecture (JCA) resource adapters and building a sample adapter that connects to the Apache James server. Section 1. Before you start This tutorial series is for J2EE and Java Platform, Enterprise Edition (Java EE) programmers who would like to learn how to build integrated solutions using various J2EE components like MDBs, JCA resource adapters, and so on. About this series This three-part series walks you through building a sample application to understand how different J2EE components can be integrated to develop complex applications. The sample application demonstrates the flow of data from an e-mail in the Apache James e-mail server to the Apache Geronimo application server via a JCA resource adapter, MDBs, and EJB. The resource adapter © Copyright IBM Corporation 1994, 2008. All rights reserved. Page 1 of 37 developerWorks® ibm.com/developerWorks Part 1 demonstrated how to develop MDBs and entity beans, and container-managed persistence (CMP) and how to deploy and test these components in Apache Geronimo. Part 2 explained how to create an e-mail application (mailers and matchers) and deploy it in Apache James. Part 3 ties the entire application together. You'll learn how to develop, deploy, and test a JCA resource adapter for Apache James that interacts with both James and Geronimo via MDB. About this tutorial This final tutorial in the three-part series explains in detail the interactions between different J2EE components (MDB and JCA adapters). You'll learn about JCA-based resource adapters and build a sample adapter that connects to the Apache James server. Prerequisites This tutorial assumes you're familiar with basic Java, J2EE, and Java EE concepts, such as Enterprise Java Beans (EJB), Java Message Service (JMS), MDBs, and Unified Modeling Language (UML) diagrams. You're not required to have any prior knowledge of JCA. However, if you would like to read the JCA specification before starting this tutorial, check the Resources section for a link. System requirements You need the following tools to follow along with this tutorial: • Apache Geronimo -- Java EE application server from Apache • Apache James 2.2 -- Java-based Simple Mail Transfer Protocol (SMTP), Post Office Protocol version 3 (POP3), and Network News Transfer Protocol (NNTP) news server • The Apache Derby database -- Open source, lightweight database that is embedded within Geronimo, so no separate installations are required • Java 1.4.2 from Sun Microsystems Example source file First, download part3.zip (available in the Download section), which includes source, adapter, MDB, and EJB binaries for Part 3. The components of part3.zip include the following: • - deploy (po.ear, which contains both the mailet and matcher) The resource adapter Page 2 of 37 © Copyright IBM Corporation 1994, 2008. All rights reserved. ibm.com/developerWorks developerWorks® • - lib (tester.jar, examples.jar, mail-1.3.1.jar, activation.jar) • - src (Java files for resource adapter, mdb, ejb and test client) • - runSendEmail.cmd • - runReadEmail.cmd Section 2. Overview In this section, you'll explore the evolution of application integration leading up to the advent of JCA. A brief history of application integration Let's travel back in time, say before 2000, when integrating heterogeneous enterprise and legacy systems (for example, SAP, Siebel, and Peoplesoft) was not only expensive, but also a very time-consuming, ad hoc process. This process, popularly known as Enterprise Application Integration (EAI) was offered as a proprietary service by various software vendors. At the end of 2000, the J2EE Connector Architecture (abbreviated as JCA and not to be mistaken for Java Cryptography Architecture) for the first time introduced standards for EAI. The advent of JCA, along with J2EE 1.3, marked a giant leap in developing integrated solutions in 2001 and set a decline for proprietary technologies in the integration space. Definitions Take a look at the following definitions before diving into resource adapters: • Enterprise Information Systems (EIS): The back-end layer where traditional data processing occurs in an organization. For this tutorial series, the Apache James server is the EIS. • Enterprise Application Integration (EAI): The process of linking various enterprise systems (EIS) in an organization. • Application Programming Interface (API) contract: A predefined set of APIs to communicate among different J2EE components. • Resource Adapter Archive (RAR): Consists of all the libraries and descriptors required by a resource adapter. The resource adapter © Copyright IBM Corporation 1994, 2008. All rights reserved. Page 3 of 37 developerWorks® ibm.com/developerWorks • Service Provider Interface (SPI): Contract defined by the JCA specification. • Common Client Interface (CCI): Contract defined by the JCA specification. What is a resource adapter? A resource adapter is a J2EE component, such as EJBs, and MDBs. As every J2EE component conforms to some specification, a resource adapter must conform to a well-defined specification called the J2EE Connector Architecture (see Resources for links to the JCA specifications). A resource adapter has an important role in an integrated J2EE solution: It's responsible for all of the communication with a back-end EIS. A resource adapter serves as a single point of entry for any J2EE component to access the back-end resource, which is usually an EIS. It's solely responsible for connecting to the EIS, invoking the services available on the EIS system, and more. A resource adapter is to an EIS system what an entity bean is to a database. A resource adapter can be deployed within a J2EE application server, which is called a managed scenario.A non-managed scenario is one where a resource adapter doesn't have to be deployed in any server and is stand alone. In this tutorial, you'll use the managed scenario, because you'll deploy your resource adapter in Apache Geronimo, which is a J2EE application server. You'll learn about the different components of a resource adapter in the later sections. First, you need to understand the specification itself. Section 3. J2EE connector architecture specification A JCA specification defines a set of contracts to manage various aspects of a resource adapter, such as connection or transaction. This section explains the contracts defined in both versions 1.0 and 1.5 of JCA. JCA 1.0 JCA 1.0 was the first specification released in November 2000. On a broader level, it defined two types of contracts, namely system-level and application-level contracts. System-level contracts define communication and handshaking between the resource adapter and the J2EE application server, whereas application-level contracts define the communication between a client application and a resource adapter. These contracts are transparent to the clients of a resource adapter. The resource adapter Page 4 of 37 © Copyright IBM Corporation 1994, 2008. All rights reserved. ibm.com/developerWorks developerWorks® System-level contracts (alternatively called SPIs) define various contracts such as: • Connection management: Defines the communication between a resource adapter and a J2EE connection manager (a component residing within a J2EE application server) to support connection pooling. The resource adapter connections to EIS are created during deployment and are pooled to increase scalability and performance. • Transaction management: Supports transaction management and defines the handshaking between the transaction manager and the resource adapter. It supports two types of transactions: local and XA. Local transactions, as the name suggests, are local to an EIS and its resource adapter. XA transactions are external to EIS and are managed by the application server transaction manager. An XA transaction is capable of encapsulating multiple calls to different resources, such as different EIS systems, databases, and so on. They support a two-phase commit protocol. • Security management: Supports different security mechanisms, such as authentication and authorization, between a resource adapter and the J2EE application server. Application-level contracts (alternatively called CCIs) define a set of client APIs for application components, such as EJB and application clients, to interact with the resource adapter. They support synchronous communication between a resource adapter and a client application originated by the client application. JCA 1.5 JCA 1.5, the latest specification, defines the missing aspects of JCA 1.0. In addition to the JCA 1.0 contracts mentioned previously, JCA 1.5 defines management contracts and inbound contracts. Let's take a look at these new contracts. JCA 1.5 has a different categorization for the supported contracts as listed below. • Outbound contracts: Three contracts specified in the JCA 1.0 section -- connection, transaction, and security management. These contracts