Enterprise Java Technologies Tech Tips Tips, Techniques, and Sample Code Welcome to the Enterprise Java Technologies Tech Tips for November 23, 2004. Here you'll get tips on using enterprise Java technologies and APIs, such as those in Java 2 Platform, Enterprise Edition (J2EE). This issue covers: * J2EE Connector Architecture 1.5 * Custom Components With JavaServer Faces Technology These tips were developed using the Java 2, Enterprise Edition, v 1.4 SDK. You can download the SDK at http://java.sun.com/j2ee/1.4/download.html. This issue of the Tech Tips is written by Robert Eckstein, a Java technology developer, editor, and author. Robert is owner of Nexes Consulting, a Java consulting firm based in Austin, Texas. You can view this issue of the Tech Tips on the Web at http://java.sun.com/developer/EJTechTips/2004/tt1123.html. See the Subscribe/Unsubscribe note at the end of this newsletter to subscribe to Tech Tips that focus on technologies and products in other Java platforms. You can download the sample archive for these tips at http://java.sun.com/developer/EJTechTips/download/ttnov2004.war. Any use of this code and/or information below is subject to the license terms at http://developers.sun.com/dispatcher.jsp?uid=6910008. For more Java technology content, visit these sites: java.sun.com - The latest Java platform releases, tutorials, and newsletters. java.net - A web forum for collaborating and building solutions together. java.com - The marketplace for Java technology, applications and services. - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - J2EE CONNECTOR ARCHITECTURE 1.5 If you've ever tried to integrate legacy systems with a J2EE application server, you know that it can be quite a challenge. Managing connections, converting between different data types, and even sending messages between an application server and an Enterprise Information System (EIS) can leave an enterprise Java programmer with quite a headache. Thankfully, there's the J2EE Connector Architecture, now in version 1.5 in J2EE 1.4, which defines a standard architecture for connecting the J2EE platform to heterogeneous EISs. Using the J2EE Connector Architecture, EIS vendors do not have to create custom connection software for multiple application servers. Neither do application server vendors have to customize their code to support various EIS packages. Instead, these vendors can package "in-between" code that conforms to the J2EE Connector Architecture specifications. The code implements or extends a set of standardized contract interfaces and classes that adapt data and messages for communication between the application server and the EIS resource. This in-between code plugs into the application server, and is called a resource adapter. A resource adapter module, typically called a Resource Adapter Archive (RAR), is simply a JAR file. A RAR typically includes the following: o Java classes and interfaces that implement the resource adapter contracts and client APIs. o Any native libraries that are required to communicate with the EIS. o A deployment descriptor file, ra.xml, that the application server uses to configure the resource adapter. The file is located in the META-INF directory. There are three important communication bridges that comprise the J2EE Connector Architecture. Let's look at each of them. Client APIs and the Common Client Interface Application components that plug into the application server must have a way of communicating with the resource adapter. The Common Client Interface (CCI) is the recommended API to do this. The CCI is an API that is implemented in the javax.resource.cci package. The API is recommended because it's easy to use, but it's not mandatory. Resource adapter implementers are free to create their own specialized client APIs to communicate with application components if the CCI does not satisfy their needs. Container-Component Contracts This is a standardized communication method between the application server and the application components. There's not much here in terms of JCA. For example, if a Web application uses Enterprise JavaBeans (EJB) components, then the EJB specification is the container-component contract that governs how each EJB component communicates with the application server. System Contracts This is a major part of the J2EE Connector Architecture. The architecture specifies several system contracts that a resource adapter must conform to in order to communicate clearly with the application server. The APIs for the system contracts are implemented in the javax.resource.spi package. The 1.0 version of the J2EE Connector Architecture introduced three such contracts: o Connection Management Contract: Provides interfaces and classes that allow for connections between the EIS and the application server. It also allows the application server to pool these connections as it deems necessary. o Transaction Management Contract: Brings atomic transaction capabilities to the EIS. The EIS can then be managed either by the resource adapter or a transaction manager. This only works one way, however. Transactions must be initiated outside the EIS and passed to it, not the reverse. o Security Contract: Ensures that there is proper authentication between the application server and the EIS. With version 1.5 of the architecture, four new contracts were created that allow greater functionality inside of a resource adapter. The new contracts are: o Lifecycle Management Contract: Provides a way for the application server to cleanly start and shutdown the resource adapter. o Work Management Contract: Provides interfaces and classes that allow resource adapters to submit work for execution by the application server. o Transaction Inflow Contract: Allows transactions to be passed from the EIS to the application server (the reverse of the Transaction Management Contract). It also assists with transaction recovery in the event that the EIS crashes. o Message Inflow Contract: Allows the resource adapter to send synchronous or asynchronous messages to endpoints within the application server. Let's examine these four new contracts in more detail. Lifecycle Management and Work Management Contracts The ResourceAdapter interface in the javax.resource.spi package represents a resource adapter. There are two methods in the ResourceAdapter interface that allow for lifecycle management: start() and stop(). The start() method is called when an application server wants to start a resource adapter (for example, to deploy it). The stop() method is called when the application server wants to release a resource adapter (for example, to undeploy it). The Work Management contract allows the resource adapter to submit work to the application server. It does this by creating an object that extends the Work interface in the javax.resource.spi.work package. The Work interface is an extension of the Runnable interface. In addition to the run() method that it inherits from Runnable and which executes in its own thread, the Work interface contains a release() method. The application server can use release() to request that the thread complete, and release its resources as soon as possible. Here is part of an example implementation of the ResourceAdapter interface that illustrates the lifecycle management and work management contracts: public class NexesResourceAdapterImpl implements ResourceAdapter { // Ten seconds public static final long WORK_START_TIMEOUT = 10000L; public NexesResourceAdapterImpl() { } public void start(BootstrapContext ctx) throws ResourceAdapterInternalException { WorkManager workManager = ctx.getWorkManager(); Work nexesWorkJob = new NexesWorkImpl(); WorkListener workListener = new NexesWorkListenerImpl(); try { // Unlike scheduleWork() or doWork(), this call // blocks until the work has started. If it takes // longer than 10 seconds for the work to start, // the call throws a WorkRejectedException. workManager.startWork (nexesWorkJob, WORK_START_TIMEOUT, new ExecutionContext(), workListener); } catch (WorkException e) { // Handle the exception } } public void stop() { // Do whatever you need to do here to close down the // resource adapter. } // Transaction Inflow contract methods omitted. // See the section "Message Inflow and Transaction // Inflow Contracts" } Notice that there is an object passed in with the start() method that implements the BootstrapContext interface. This is an important object that allows the EIS to pass transaction information to the application server, as well as the ability to pass work to the application server. See the section "Message Inflow and Transaction Inflow Contracts" for more details about the BootstrapContext interface. Also notice the reference to the WorkListener interface: WorkListener workListener = new NexesWorkListenerImpl(); and the startWork method: workManager.startWork (nexesWorkJob, WORK_START_TIMEOUT, new ExecutionContext(), workListener); If you want the application server to notify you about the progress of any work that is submitted, you can create an object that implements the javax.resource.spi.WorkListener interface. You can then register this object using the startWork() method of the WorkManager object on the application server. The WorkManager interface provides a facility to submit Work instances for execution. Registering the object allows the server to notify the resource adapter if the work was rejected or accepted, and if accepted, when the work was started and completed. You can also extend the WorkAdapter class, which implements the WorkListener interface and provides empty methods for each of these. Here is skeleton code for a class that implements WorkListener: public class NexesWorkListenerImpl implements WorkListener { public void workAccepted(WorkEvent e) { // myAppServerLog.log("Work instance " + e + // " has been accepted."); } public void workRejected(WorkEvent e) { // myAppServerLog.log("Work instance " + e + // " has been rejected."); } public void workStarted(WorkEvent e) { // myAppServerLog.log("Work instance " + e + // " has been started."); } public void workCompleted(WorkEvent e) { // myAppServerLog.log("Work instance " + e + // " has been completed."); } } Message Inflow and Transaction Inflow Contracts The Message Inflow contract allows the resource adapter to react to calls made by the application server to activate and deactivate message endpoints. The endpointActivation() method in the ResourceAdapter interface is called during endpoint activation. This causes the resource adapter to do the necessary setup for message delivery to the message endpoint. The endpointDeactivation() method of ResourceAdapter is called when a message endpoint is deactivated. This stops the resource adapter from delivering messages to the message endpoint. A MessageEndpointFactory object in the javax.resource.spi.endpoint package is passed in to the endpointActivation method. The object is used by the resource adapter to create a number of message endpoints. Any information about these endpoints should be removed from the resource adapter when the endpointDeactivation() method is called. Finally, the getXAResources() method of ResourceAdapter can be used to retrieve transaction resources in the event of a system crash. The endpointActivation(), endpointDeactivation(), and getXAResources() methods are mandated by the ResourceAdapter interface. public class NexesResourceAdapterImpl implements ResourceAdapter { // Lifecycle Contract methods from earlier omitted. public XAResource[] getXAResources(ActivationSpec[] specs) throws ResourceException { // This method should either return an array of // XAResource objects that uniquely correspond to the // resource manager given the ActivationSpecs passed // in, or null if it does not support this par // of the Message Inflow contract. return null; } public void endpointActivation(MessageEndpointFactory mef, ActivationSpec as) throws NotSupportedException { // This is also part of the Message Inflow contract. // The idea here is to create a message endpoint // using the MEF's createEndpoint() method, which is // then stored in the ActivationSpec class. This binds // the EIS and the application server together so that // the two can communicate independently of the // messaging style of the EIS. } public void endpointDeactivation(MessageEndpointFactory mef, ActivationSpec as) { // This removes any resources that were created by the // endpointActivation() method above for the specified // messaging endpoint. The resource adapter must notify // any message providers that the endpoint is no longer // valid } } The ActivationSpec class that is passed in to the ResourceAdapter methods is a JavaBean that implements a number of get and set methods for various properties. In addition to providing these get and set methods, an implementation must also provide a validate() method to ensure that all of the properties have been legally set. If a property has not been set properly, the method must throw an InvalidPropertyException. Note that an ActivationSpec object cannot override equals(). public class MyActivationSpec implements ActivationSpec, Serializable { public void setMyProperty(MyProperty s) { } public MyProperty getMyProperty() { } public void validate() throws InvalidPropertyException { } } In version 1.0 of the J2EE Connector Architecture, a resource adapter could only pass transaction information to the EIS, either from itself or from an external transaction manager. However with the Transaction Inflow contract in version 1.5 of the architecture, the resource adapter can pass EIS transaction requests to the application server as well as use the BootstrapContext object that is passed in with the start() method of the Lifecycle Contract. The BootStrapContext interface was mentioned briefly in the discussion of the Lifecycle Management contract. Here are the methods in the BootstrapContext interface: public class NexesBootstrapContextImpl implements BootstrapContext { public WorkManager getWorkManager() { // Get the work manager from the application server } public XATerminator getXATerminator() { return new NexesXATerminatorImpl(); } public Timer createTimer() { return new Timer(); } } Let's also take a closer look at the XATerminator interface. Notice that it's the return type of the getXATerminator() method in the BootStrapContext interface. The XATerminator interface contains five simple methods that handle transactions: public class NexesXATerminatorImpl implements XATerminator { public void commit(Xid xid, boolean onePhase) throws XAException { } public void forget(Xid xid) throws XAException { } public int prepare(Xid xid) throws XAException { } public Xid[] recover(int flag) throws XAException { } public void rollback(Xid xid) throws XAException { } } The Resource Adapter File The resource adapter descriptor file, ra.xml, is fairly easy to create. You simply need to point in the file to the class that implements the ResourceAdapter interface. The application server will then access that class. See the J2EE Connector Architecture 1.5 specifications (http://java.sun.com/j2ee/connector/download.html) for more information on resource adapter deployment descriptors, including how to tie incoming message classes to ActivationSpec classes. Like all deployment descriptors, the ra.xml file needs to be in the WEB-INF directory of the WAR file. Skeleton Resource Adapter Sun Microsystems, Inc. Unknown 1.0 com.nexes.ra.NexesResourceAdapterImpl For more information about the J2EE Connector Architecture, see the J2EE Connector Architecture page (http://java.sun.com/j2ee/connector/index.jsp). ---------------------------------------------------------------- CUSTOM COMPONENTS WITH JAVASERVER FACES TECHNOLOGY The March 24, 2004 Tech Tip "Improving Designs With the MVC Design Pattern" (http://java.sun.com/developer/EJTechTips/2004/tt0324.html#1) introduced the architectural pattern known as Model,View, Controller (MVC or Model2). MVC is a pervasive pattern throughout the world of computer science, and is fundamental to understanding JavaServer Faces (JSF) technology. The pattern separates the data and business logic of an application from its visual representation. The data and business logic is stored in an object called the Model. The visual representation is stored in a separate object called the View. The two objects are linked together with a third object called the Controller. The controller reacts to input from the view and updates the model data accordingly. The advantage of using this design is that any changes to the business logic or data can be isolated to the model without affecting the view. You can create multiple views without affecting the model. A second tip in the March 24, 2004, titled "Introducing JavaServer Faces Technology" (http://java.sun.com/developer/EJTechTips/2004/tt0324.html#2) showed how to create a JSF application that includes GUI components that are modeled by the JSF framework. In this tip, you'll learn how to create custom components using JSF technology. More specifically, you'll learn how to create a custom JSF technology component that represents a simple stock display. Through an accompanying JavaServer Pages (JSP) page, a user can enter a stock symbol into a input text field and then press the Submit button. In response, the custom component displays a table below the text field. The table contains the stock's symbol, the current price of the stock, and the daily change in the stock price. This tip assumes that you are familiar with the basics of JSF technology, and you know how to create JSP technology custom tag libraries. For information on the basics of JSF technology, see "An Introduction to JavaServer Faces" (http://java.sun.com/j2ee/javaserverfaces/jsfintro.html). For information on creating your own JSP custom tag libraries, see "Using Custom Tags" (http://java.sun.com/j2ee/1.4/docs/tutorial/doc/JSPIntro9.html#wp73314) in the J2EE 1.4 Tutorial. To create the custom component, you need to: o Create a JavaBean Model class that can be used to retrieve the stock data o Create a custom JSF View output component class that extends javax.faces.component.UIComponent. o Create a custom JSF View class that extends javax.faces.render.Renderer. o Integrate the custom component into the JSF framework using a custom tag. o Create a JSP page, including an input text field, and a backing bean for the input text field to assist the custom component. Create a JavaBean Model The model for the stock component is simple JavaBean class that has get and set accessor methods to store and retrieve data. The bean also has a method, retrieveStock(), that the UI component calls when the user enters the stock symbol. This method takes the entered stock symbol and updates the model information accordingly. The sample archive that accompanies this tip includes all the source code for the stock component. In it you'll find the following source code for the class StockModel, the Model component: public class StockModel { private String selectedStock = "UNKNOWN"; private String currentValue = "0"; private String dailyChange = "0"; public String getSelectedStock() { return selectedStock; } public String getCurrentValue() { return currentValue; } public String getDailyChange() { return dailyChange; } public void retrieveStock(String stockSubmitted) { selectedStock = stockSubmitted; currentValue = "23.5"; dailyChange = "+2.5"; } } Typically a method such as retrieveStock() would query a database to obtain the data, but for simplicity, the method in this class updates the rest of the model with the constant strings specified in the class. Create a UI Component The primary purpose of the UI Component, which is part of the view, is to take data from the model and either display it itself, or relay it to a custom renderer to display the data as necessary. A custom UI component extends javax.faces.component.UIComponent. This class extends javax.faces.component.UIOutput, where the UIOutput class is a subclass of the UIComponent class. With UIOutput, most of the view functionality that is needed by the custom component is already provided. The only addition that this class needs is the getFamily() method, which returns a String that describes the component family (this must match an entry in the resource descriptor later). Here is the source code for the class UIStockChoiceOutput: public class UIStockChoiceOutput extends UIOutput { public static final String STOCK_FAMILY = "StockFamily"; public UIStockChoiceOutput() { super(); } public String getFamily() { return STOCK_FAMILY; } } Create a Custom Renderer The next step is to create a renderer for how this JSF component should appear in the client browser. This is a custom View class that extends the javax.faces.render.Renderer class. The purpose of this renderer is to create the output HTML table for the stock information display. Although it is not the case here, renderers can also be responsible for rendering input. Hence, a renderer can perform two types of translation services: decoding any input data into a format that can be passed on to the controller, and encoding any data from the controller object and rendering it to the browser. Decoding is done by the decode() method in the renderer. Encoding can be done by a number of encoding methods. This example uses the encodeEnd() method. Here is an extract of the source code for SimpleStockRenderer, the renderer (and custom View component): public class SimpleStockRenderer extends Renderer { public void encodeEnd(FacesContext context, UIComponent component) throws IOException { if (!component.isRendered()) return; String selectedStock = (String)component.getAttributes().get("selectedStock"); String currentValue = (String)component.getAttributes().get("currentValue"); String dailyChange = (String)component.getAttributes().get("dailyChange"); String id = (String)component.getClientId(context); ResponseWriter out = context.getResponseWriter(); out.startElement("table", component); out.writeAttribute("border", "0", "border"); out.startElement("tr", component); out.writeAttribute("bgcolor", "#000077", "bgcolor"); writeTableHeader(out, component, "Stock Symbol"); writeTableHeader(out, component, "Current Value"); writeTableHeader(out, component, "Daily Change"); out.endElement("tr"); out.startElement("tr", component); out.writeAttribute("bgcolor", "#FFFFFF", "bgcolor"); writeTableEntry(out, component, selectedStock); writeTableEntry(out, component, currentValue); writeTableEntry(out, component, dailyChange); out.endElement("tr"); out.endElement("table"); } // Methods writeTableEntry() and writeTableHeader() omitted } Notice that a FacesContext object and a UIComponent object are passed in to the encodeEnd() method. The FacesContext object contains information about the JSF environment. The UIComponent is a reference to the Controller object. The encodeEnd() method retrieves the model data through the UIComponent controller and creates a ResponseWriter object. The method uses this object to write the HTML elements and their attributes for the HTML table, including its headers. There are a number of other encode methods in the Renderer class. See the JSF specification (http://java.sun.com/j2ee/javaserverfaces/download.html) for information about these methods. Create the Backing Bean The next step is to create a backing bean for the input component. The backing bean provides a String-based property accessor for the input stock, as well as a boolean (rendered) indicating whether the output table should appear. Note that a validator has been added to the source code as well. If the input is not valid, the rendered boolean is set to false, and the renderer will not display the output table. The source code for the backing bean is shown here: public class InputBackingBean { private String inputStock = ""; private boolean rendered = false; public void setStockOutputRendered(boolean r) { rendered = r; } public boolean getStockOutputRendered() { return rendered; } public String getInputStock() { return inputStock; } public void setInputStock(String stock) { inputStock = stock; } public void validateStock (FacesContext ctx, UIComponent component, Object value) throws ValidatorException { public void validateStock(FacesContext ctx, UIComponent component, Object value) throws ValidatorException { String string = (String)value; if ((value.equals("AAA")) || (value.equals("BBB")) || (value.equals("CCC")) || (value.equals("DDD")) || (value.equals("EEE")) || (value.equals("FFF")) || (value.equals("GGG")) || (value.equals("HHH"))) { rendered = true; } else { rendered = false; throw new ValidatorException( new FacesMessage ("Invalid Stock Entry: (Enter AAA,BBB, etc.)")); } } public String inputStockSubmitted() { FacesContext context = FacesContext.getCurrentInstance(); StockModel model = (StockModel) context.getApplication().getVariableResolver().resolveVariable( context, "StockModel"); model.retrieveStock(inputStock); return "Input Stock Accepted"; } } The inputStockSubmitted() method is very important. This method is tied to an action attribute of a (which is a Submit button in the JSP page). When invoked, the method retrieves the StockModel by resolving it through the current faces context. The retrieveStock() method is then called on the model to update the stock information in the output table. Final Steps There are a few other things that need to be done to use the custom component. The component requires a custom tag library class that the JSP framework uses to communicate data to and from a JSP file. The class SimpleStockInputTag.java is the custom tag library class used in this tip. The custom tag library for this tip is called "stock". The JSF framework also needs to way to tie the Model bean to the custom tag. It uses a standard JSP tag library descriptor file to do this. You can find the JSP tag library descriptor file, stock.tld, in the WEB-INF/lib directory of the sample archive. The custom component objects must be registered with the JSF architecture. This is done through a faces-config.xml file in the WEB-INF directory. Finally, you need a JSP page to display the component, provide a Submit button, and display the component. Here is most of the JSP page, Stock.jsp, that displays the component: ... <%@taglib prefix="stock" uri="http://nexes.org/example/stock"%> Stock Choice Example

Please Enter a Stock Symbol

 Running the Sample Code Download the sample archive (http://java.sun.com/developer/EJTechTips/download/ttnov2004.war) for these tips. The application's context root is ttnov2004. The downloaded war file also contains the complete source code for the sample. You can deploy the application archive (ttnov2004.war) on the J2EE 1.4 Application Server using the deploytool program or the admin console. You can also deploy it by issuing the asadmin command as follows: asadmin deploy install_dir/ttnov2004.war Replace install_dir with the directory in which you installed the war file. You can access the application at http://localhost:8000/ttnov2004 For a J2EE 1.4-compliant implementation other than the J2EE 1.4 Application Server, use your J2EE product's deployment tools to deploy the application on your platform. . . . . . . . . . . . . . . . . . . . . . . . Please read our Terms of Use and Licensing policies: http://www.sun.com/share/text/termsofuse.html http://developers.sun.com/dispatcher.jsp?uid=6910008 PRIVACY STATEMENT: Sun respects your online time and privacy (http://sun.com/privacy). You have received this based on your e-mail preferences. If you would prefer not to receive this information, please follow the steps at the bottom of this message to unsubscribe. * FEEDBACK Comments? Send your feedback on the Enterprise Java Technologies Tech Tips to: http://developers.sun.com/contact/feedback.jsp?category=sdn * SUBSCRIBE/UNSUBSCRIBE Subscribe to other Java developer Tech Tips: - Core Java Technologies Tech Tips. Get tips on using core Java technologies and APIs, such as those in the Java 2 Platform, Standard Edition (J2SE). - Wireless Developer Tech Tips. Get tips on using wireless Java technologies and APIs, such as those in the Java 2 Platform, Micro Edition (J2ME). To subscribe to these and other JDC publications: - Go to the Sun Developer Netwrok - Subscriptions page, (https://softwarereg.sun.com/registration/developer/en_US/subscriptions), choose the newsletters you want to subscribe to and click "Submit". - To unsubscribe, go to the Subscriptions page, (https://softwarereg.sun.com/registration/developer/en_US/subscriptions), uncheck the appropriate checkbox, and click "Submit". - To use our one-click unsubscribe facility, see the link at the end of this email: - ARCHIVES You'll find the Enterprise Java Technologies Tech Tips archives at: http://java.sun.com/developer/EJTechTips/index.html - COPYRIGHT Copyright 2004 Sun Microsystems, Inc. All rights reserved. 901 San Antonio Road, Palo Alto, California 94303 USA. This document is protected by copyright. For more information, see: http://java.sun.com/developer/copyright.html Enterprise Java Technologies Tech Tips November 23, 2004 Trademark Information: http://www.sun.com/suntrademarks/ Java, J2SE, J2EE, J2ME, and all Java-based marks are trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.