1RYHOO H[WH1G &RPSRVHU (QWHUSULVH 6HUYHU IRU 1RYHOO H[WH1G $SSOLFDWLRQ 6HUYHU

Препис

1 1RYHOO H[WH1G&RPSRVHU Π(QWHUSULVH 6HUYHU IRU 1RYHOO H[WH1G $SSOLFDWLRQ 6HUYHU 86(5 6*8,'(

2 Legal Notices Copyright 1999, 2000, 2001, 2002, 2003 SilverStream Software, LLC. All rights reserved. SilverStream software prodcts are copyrighted and all rights are reserved by SilverStream Software, LLC SilverStream is a registered trademark of SilverStream Software, LLC. Novell is a registered trademark of Novell, Inc. Title to the Software and its docmentation, and patents, copyrights and all other property rights applicable thereto, shall at all times remain solely and exclsively with SilverStream and its licensors, and yo shall not take any action inconsistent with sch title. The Software is protected by copyright laws and international treaty provisions. Yo shall not remove any copyright notices or other proprietary notices from the Software or its docmentation, and yo mst reprodce sch notices on all copies or extracts of the Software or its docmentation. Yo do not acqire any rights of ownership in the Software. Jakarta-Regexp Copyright 1999 The Apache Software Fondation. All rights reserved. Ant Copyright 1999 The Apache Software Fondation. All rights reserved. Xalan Copyright 1999 The Apache Software Fondation. All rights reserved. Xerces Copyright The Apache Software Fondation. All rights reserved. Jakarta-Regexp, Ant, Xalan, Crimson and Xerces software is licensed by The Apache Software Fondation and redistribtion and se of Jakarta- Regexp, Ant, Xalan, Crimson and Xerces in sorce and binary forms, with or withot modification, are permitted provided that the following conditions are met: 1. Redistribtions of sorce code mst retain the above copyright notices, this list of conditions and the following disclaimer. 2. Redistribtions in binary form mst reprodce the above copyright notice, this list of conditions and the following disclaimer in the docmentation and/or other materials provided with the distribtion. 3. The end-ser docmentation inclded with the redistribtion, if any, mst inclde the following acknowledgment: "This prodct incldes software developed by the Apache Software Fondation ( Alternately, this acknowledgment may appear in the software itself, if and wherever sch third-party acknowledgments normally appear. 4. The names "The Jakarta Project", "Jakarta-Regexp", "Xerces", "Xalan", "Ant" and "Apache Software Fondation" mst not be sed to endorse or promote prodcts derived from this software withot prior written permission. For written permission, please contact apache@apache.org <mailto:apache@apache.org>. 5. Prodcts derived from this software may not be called "Apache", nor may "Apache" appear in their name, withot prior written permission of The Apache Software Fondation. THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Copyright 2000 Brett McLaghlin & Jason Hnter. All rights reserved. Redistribtion and se in sorce and binary forms, with or withot modification, are permitted provided that the following conditions are met: 1. Redistribtions of sorce code mst retain the above copyright notice, this list of conditions, and the following disclaimer. 2. Redistribtions in binary form mst reprodce the above copyright notice, this list of conditions, and the disclaimer that follows these conditions in the docmentation and/or other materials provided with the distribtion. 3. The name "JDOM" mst not be sed to endorse or promote prodcts derived from this software withot prior written permission. For written permission, please contact license@jdom.org <mailto:license@jdom.org>. 4. Prodcts derived from this software may not be called "JDOM", nor may "JDOM" appear in their name, withot prior written permission from the JDOM Project Management (pm@jdom.org <mailto:pm@jdom.org>). THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

3 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. Sn Microsystems, Inc. Sn, Sn Microsystems, the Sn Logo Sn, the Sn logo, Sn Microsystems, JavaBeans, Enterprise JavaBeans, JavaServer Pages, Java Naming and Directory Interface, JDK, JDBC, Java, HotJava, HotJava Views, Visal Java, Solaris, NEO, Joe, Netra, NFS, ONC, ONC+, OpenWindows, PC-NFS, SNM, SnNet Manager, Solaris snbrst design, Solstice, SnCore, SolarNet, SnWeb, Sn Workstation, The Network Is The Compter, ToolTalk, Ultra, Ultracompting, Ultraserver, Where The Network Is Going, SnWorkShop, XView, Java WorkShop, the Java Coffee Cp logo, Visal Java, and NetBeans are trademarks or registered trademarks of Sn Microsystems, Inc. in the United States and other contries. Copyright 2001 Extreme! Lab, Indiana University License. Permission is hereby granted, free of charge, to any person obtaining a copy of the Indiana University software and associated Indiana University docmentation files (the "IU Software"), to deal in the IU Software withot restriction, inclding withot limitation the rights to se, copy, modify, merge, pblish, distribte, sblicense, and/or sell copies of the IU Software, and to permit persons to whom the IU Software is frnished to do so, sbject to the following conditions: The above copyright notice and this permission notice shall be inclded in all copies or sbstantial portions of the IU Software. THE IU SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE IU SOFTWARE OR THE USE OR OTHER DEALINGS IN THE IU SOFTWARE. This Software is derived in part from the SSLavaTM Toolkit, which is Copyright by Phaos Technology Corporation. All Rights Reserved. Copyright W3C (Massachsetts Institte of Technology, Institt National de Recherche Informatiqe et en Atomatiqe, Keio University), all Rights Reserved. http: This W3C work (inclding software, docments, or other related items) is being provided by the copyright holders nder the following license. By obtaining, sing and/or copying this work, yo (the licensee) agree that yo have read, nderstood, and will comply with the following terms and conditions: Permission to se, copy, modify, and distribte this software and its docmentation, with or withot modification, for any prpose and withot fee or royalty is hereby granted, provided that yo inclde the following on ALL copies of the software and docmentation or portions thereof, inclding modifications, that yo make: 1. The fll text of this NOTICE in a location viewable to sers of the redistribted or derivative work. 2. Any pre-existing intellectal property disclaimers, notices, or terms and conditions. If none exist, a short notice of the following form (hypertext is preferred, text is permitted) shold be sed within the body of any redistribted or derivative code: "Copyright [$date-of-software] World Wide Web Consortim, (Massachsetts Institte of Technology, Institt National de Recherche en Informatiqe et en Atomatiqe, Keio University). All Rights Reserved Notice of any changes or modifications to the W3C files, inclding the date changes were made. (We recommend yo provide URIs to the location from which the code is derived.) THIS SOFTWARE AND DOCUMENTATION IS PROVIDED "AS IS," AND COPYRIGHT HOLDERS MAKE NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIES OF MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE OR DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS. COPYRIGHT HOLDERS WILL NOT BE LIABLE FOR ANY DIRECT, INDIRECT, SPECIAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF ANY USE OF THE SOFTWARE OR DOCUMENTATION. The name and trademarks of copyright holders may NOT be sed in advertising or pblicity pertaining to the software withot specific, written prior permission. Title to copyright in this software and any associated docmentation will at all times remain with copyright holders.

4 Novell, Inc Soth Novell Place Provo, UT RYHOOH[WH1G&RPSRVHU(QWHUSULVH6HUYHU*XLGH -DQXDU\ Online Docmentation: To access the online docmentation for this and other Novell prodcts, and to get pdates, see

5 Contents Abot This Gide 9 Welcome to extend Composer Enterprise Server 13 What is XML? What is Server? Abot Components and Services Composer Enterprise Server Overview 17 Server Specifications Prodction Rntime Environment Metadata Architectre Deployment Options Administrative Control of Composer Enterprise Server Cache Tning Least-Recently-Used (LRU) Cache Algorithm Updating Yor License Planning Yor Deployment 25 Web Services verss JMS Services Standalone Deployment Integrated Application Deployment Connection Pools How Are Pools Identified? Connectors Proxy Servers Secrity Roles Pblishing XML Resorces Additional Java Classes Deploying a Project 31 Determining the Rntime Environment Creating Deployment Objects Installing Deployment Objects Abot Service Triggers for Web Services Servlet Based Service Triggers EJB Based Service Triggers Application Based Service Triggers SOAP-Based Service Triggers JMS Service Triggers Using the Composer Deployment Wizard The General Information Panel

6 The Servlet Based Service Triggers Panel The EJB Based Service Triggers Panel The Servlet-to-EJB Triggers Panel The SOAP-Based Triggers Panel The Resorces Deployment Panel The Project Variable Remapping Panel The JMS Service Trigger Panel The Atomatic Installation Panel Administration of Deployed Projects Installing Deployment Objects Using SilverCmd SilverCmd Instrctions Pblishing XML Resorces in the Application Server Deploying XML Resorce JAR Files Programmatic Access to Composer Services 57 Extending Composer s Service Trigger Hierarchy Service Component Names within Framework Objects How to Create Service Trigger Extensions Creating Servlet-Based Service Triggers GXSServiceRnner Creating Cstom Servlet EJB Based Service Triggers Creating Service Triggers From Scratch What Is Available in the Framework Utilizing Service EJBs In an Application Using the extend Workbench to Create Cstom Triggers Transaction Management 67 Transaction Control in extend Composer Transaction Deployment Considerations for the Extend Application Server Servlet Deployment Considerations EJB Deployment EJB Deployment Considerations JDBC Transaction Control: Allowing User Transactions References $ extend Application Server Dependencies 75 Connections Using Novell extend Connection Pools % Contents of Deployment Objects 77 Project JAR Servlets EJBs ImportObjects.bat Composer Enterprise Server User s Gide

7 & Deployment Framework API Docmentation 81 Classes and Interfaces XSL Fnctionality Classes with XSL Methods ' Reserved Words 87 ( Server Glossary 89

8 Composer Enterprise Server User s Gide

9 Abot This Gide Prpose This gide describes how to se extend Composer Enterprise Server to deploy Composer applications. As sch, it is an adjnct to the extend Composer User s Gide. Adience This gide is aimed at the application server administrator and/or persons tasked with deployment of Composer services. Prereqisites This book assmes prior familiarity with the extend Composer design-time environment and Composer application-bilding metaphors. Yo shold also be familiar with Java archive formats (WAR, EAR, JAR) and web service deployment concepts in general. Organization This gide is organized as follows: Chapter Chapter 1, Welcome to extend Composer Enterprise Server Chapter 2, Server Overview Chapter 3, Planning Yor Deployment Description Gives a definition and overview of the extend site of prodcts. Briefly describes extend Composer Enterprise Server specifications and the prodction rntime environment. Otlines the key environmental and resorcerelated factors that shold be considered before deploying a Composer service. Abot This Gide

10 Chapter Chapter 4, Deploying a Project Chapter 5, Using the Deployment Framework Chapter 6, Transaction Management Appendix A, Extend Application Server Dependencies Appendix B, Contents of Deployments Objects Description Explains the available Service Trigger options and how to se the extend Composer Deployment Wizard. Describes how to cstomize or extend the application server framework classes for nonstandard deployments. Read this chapter if yo need to se cstom service triggers. Describes options for controlling the transactional aspects of yor application. Describes database connection-pool isses specific to deployment in the Extend Application Server. Describes the content of the files that are installed into the application server. Appendix C, Deployment Framework API Docmentation Describes the extend Composer Enterprise Server Java framework files. Appendix D, Reserved Words Appendix E, Glossary A listing of keywords that are sed by Composer and shold be avoided in yor code. Definitions of terms sed in this gide. Conventions This gide ses the following stylistic and typographical conventions. Bold serif typeface within instrctions indicate action items, inclding: Men selections Form selections Dialog box items Bold sans-serif typeface indicates: Uniform Resorce Identifiers File names Composer Enterprise Server User s Gide

11 Italic typeface indicates: Variable information that yo spply Technical terms sed for the first time Title of other Novell pblications Monospaced typeface indicates: Method names Code examples System inpt Operating system objects Additional docmentation For the complete set of Novell extend Director docmentation, see the Novell Docmentation Web Site:

12 Composer Enterprise Server User s Gide

13 Welcome to extend Composer Enterprise Server Chapter 1 Novell extend is a site of bsiness-to-bsiness integration server prodcts that significantly redces the time reqired to enable, integrate and deploy powerfl ecommerce applications by sing extensible Markp Langage (XML) as the primary information exchange medim. The extend site consists of three prodcts: extend Composer a visal design environment for creating B2B integration applications extend Composer Enterprise Server a rntime environment that exectes the applications created in extend Composer extend Composer Connectors a family of prodcts that extend the capabilities of extend Composer and Server to permit the XML-enablement of enterprise information sorces sch as databases, host applications, and Java components. The focs of this Gide is extend Composer Enterprise Server. Please refer to the extend Composer User s Gide for information on extend Composer, and to the User s Gides for the specific extend Composer Connects that yo need to incorporate into yor ecommerce applications. What is XML? extensible Markp Langage (XML), a sbset of Standard Generalized Markp Langage (SGML), is a docment standard adopted by the World Wide Web Consortim early in Essentially, XML is a general-prpose metalangage designed to facilitate platform-independent interchange of strctred data. Properly sed, XML makes it possible for software applications to receive and process bsiness information withot knowing anything abot how that information was created. In addition, XML s athors were mindfl of creating a data langage that wold travel well over Hypertext Transfer Protocol (HTTP), the primary information exchange protocol of the Web. Welcome to extend Composer Enterprise Server

14 What is Server? extend Composer Enterprise Server (or Server, for short) is the rntime environment for applications developed with extend Composer. It is a Java application that rns in the context of an enterprise application server. Server provides both the rntime exection engine, which interprets and processes the XML metadata deployed from Composer, and an application server tailored framework that provides integration with services provided by an application server (e.g., thread management, connection pooling, load balancing, failover and secrity). This gide assmes that yo have chosen to deploy yor Composer applications into the Extend Application Server. Abot Components and Services extend is based on an Action Model architectre that incldes two main processing constrcts: components and services. Components are exectable nits of work (implemented as action lists) that are more or less granlar, depending on ser preferences and the needs of specific integrations. For example, a typical JDBC component validates an incoming XML reqest docment, maps the docment s key information to a SQL inqiry, and maps the SQL reslt set to an XML response docment. Services typically comprise mltiple components and perform important flow management tasks sch as event handling, roting, logging and exception processing. A typical service incldes components that receive one or more XML docments, perform sophisticated docment mapping and transformations, collect additional information from JDBC data sorces, execte transactions, process error conditions, send context-sensitive messages, and retrn one or more XML response docments to the original reqestors. A service is extend s nit of deployment and is the object that is instantiated from a Servlet or EJB on the application server. Two types of services are spported: Web Services, and JMS Services. (JMS stands for Java Messaging Service, a Sn-defined interface to message-oriented middleware.) Yo can also deploy Web Services in SOAP-wrappered form. The Web Service category incldes all services that are designed to be invoked via data arriving over HTTP. The JMS Service category incldes services that are designed to be invoked by the arrival of messages on message qees or message topics. 127(The JMS Service is relevant only if yo have prchased and installed the Novell extend JMS Connect. Composer Enterprise Server User s Gide

15 The illstration below shows, in a generalized sense, how Server fits into the extend site of tools. Figre 1-1 As the accompanying illstration shows, yo se Composer to create components and services that perform desired integration tasks. Then yo deploy these components and services into a prodction application server environment, where they are exected by extend Composer Enterprise Server. extend s Connectors provide both XML enablement of enterprise bsiness systems and rntime management of interactions between those applications. Together, the extend prodct site allows yo to do the following: Heterogeneos docment mapping Receive XML-formatted data from any XML enabled application; map, transform, or convert that data to a different XML docment type; send the reslting XML-formatted data to any other XML enabled application. Integration control processing Manage all processing activities associated with yor integration applications inclding events, repeating and groping constrcts, conditions, errors, logs, cstom ECMAScript fnctions, and mch more. Host application XML enablement sing terminal data interfaces Welcome to extend Composer Enterprise Server

16 Read data from an XML docment and map, transform, or transfer it directly to a terminal transaction, or read data directly from the reslt of a terminal transaction and map it to an XML docment. Examples of poplar terminal transaction types are 3270 and XML enablement of terminal data interfaces occrs via extend s 3270 and 5250 Connects. Host application XML enablement sing transaction and message-based programming interfaces Read data from an XML docment and map, transform, or transfer it directly to a COBOL/CICS Procedre Division (e.g., sing a COMMAREA or Message Qee), or read data from a COBOL Procedre Division and map it to an XML docment. XML enablement of transaction- and message-based programming interfaces is provided throgh extend s CICS RPC and JMS Connects. Host application XML enablement sing website content retrieval ( screen scraping ) Read data from a remote web page; map, transform, or convert HTML DOM elements to XML DOM elements; and send the reslting XML-formatted data to any other XML enabled application. This fnctionality is available throgh extend s HTML Connect. Database XML enablement sing JDBC interfaces Read data from an XML docment and map, transform, or transfer it directly into an SQL transaction (via JDBC), or read data directly from the reslt of an SQL transaction and map it to an XML docment. XML enablement of JDBC data sorces is provided throgh extend s Connect for JDBC. Java XML enablement Develop and incorporate Java objects directly into yor integration applications. XML data can be passed to these objects, processed in Java, and retrned to extend for frther maniplation and mapping. Alternatively, Java objects can access extend Composer Enterprise Server s framework APIs (discssed in a later chapter) to perform advanced maniplation sch as cstom docment management and event processing. Composer Enterprise Server User s Gide

17 Composer Enterprise Server Overview Chapter 2 Server Specifications extend Composer Enterprise Server is a 100% Java and XML application consisting of a rntime engine and an application framework. The rntime engine provides the following: XML parsing XSL processing Interpretation of XML application object metadata Instantiation and exection of Connect objects via installable factories. The application framework consists partly of base classes that are environment independent and partly of classes tailored to each application server within which extend Composer Enterprise Server exectes. Classes that are application server specific inclde the following: Logging Connection pooling Transaction control Uniqe Service Triggers like mltipart reqest processing Server s framework can also be extended to incorporate additional services sch as pre- and post-processing of XML docments, enhanced secrity, and SOAP (Simple Object Access Protocol) processing. Composer Enterprise Server Overview

18 Prodction Rntime Environment Metadata Architectre Each application object (e.g., component, service, connection, and code table) is stored as an XML docment (metadata). The application metadata is exected by the Server rntime engine to perform the defined operations. By representing its application objects as XML metadata, extend generates components and services that can be readily viewed and managed by a wide range of standard tools. Deployment Options From Composer s main men, extend provides a wizard to help yo package and deploy yor project into yor application server. The Deployment Wizard provides the following capabilities: Packaging of project resorces into a JAR file Generation of Java code for Service Triggers (EJB and Servlet) if reqired Generation of EJB wrappers and Deployment Descriptor Files if reqired Atomatic loading and compiling of all generated code and metadata JARs directly from the wizard into yor application server The choices made when initially deploying the application are saved in an XML file and are restored the next time yo invoke the Deployment Wizard. Yo can either change or keep these choices dring each sbseqent deployment session. If no changes to deployment options are reqired, the project can be redeployed flly from the first Deployment Wizard screen. Optionally, yo may perform a manal deployment by configring Composer to deposit generated metadata, along with appropriate SilverCmd files, into a staging directory. This techniqe is commonly sed in large installations where the responsibility of application deployment reside with a Server Administrator. Once Composer generates all needed deployment files, the Administrator can then install them into the application server sing standards defined by yor IT organization. As an additional option, the deployment objects can be manally loaded into the extend Application Server via the extend Developer Workbench application. See Chapter 4, Deploying a Project for more information abot deployment options. Composer Enterprise Server User s Gide

19 Administrative Control of Composer Enterprise Server Once projects are deployed, yo can manage varios aspects of Composer Enterprise Server s rntime operation throgh the se of an HTML browser console. ½ To access the server management console: Be sre the application server is rnning, with Composer Enterprise Server installed and operational. Lanch yor web browser. Navigate to the host address and port from which the Composer application server is serving. (For example, A master console window will appear, with a list of choices. On the master console window, choose the extend Composer link. A new console screen appears. Click the Console link. The Composer Enterprise Server main console appears. Composer Enterprise Server Overview

20 Click the Apply Log Level btton if yo want to change the log-message threshold for yor Composer project(s). Click the Clear Cache btton if yo want to prge all objects from the cache immediately. Enter new cache settings as desired (see discssion immediately below), then click the Apply Cache Settings btton to make yor new settings take effect. 127(The Clear Cache and Apply bttons operate in real time. That is, yo do not need to restart Composer Enterprise Server in order for changes to take effect. Changes take effect immediately. Composer Enterprise Server User s Gide

21 Cache Tning The Advanced tab on the Composer Enterprise Server administrative console (above) has information abot resorce caching and gives yo the ability to set varios caching parameters. The ser-controllable parameters available nder Cache Tning are discssed below. Yo shold note that althogh the word Component is sed in many places on the Advanced console (above), cached objects inclde not only Composer Components bt other xobjects as well. In other words, components are not the only objects that get cached; other xobject types, sch as services, resorces (Code Tables, Connection objects, Cstom Script objects, etc.), XML templates, etc., are also cached. Least-Recently-Used (LRU) Cache Algorithm Composer Enterprise Server handles cache management atomatically, via a least-recently-sed (LRU) algorithm: xobjects, once instantiated, are kept in memory (or cached) ntil some predetermined nmber of cached objects has been reached or exceeded, at which point least recently sed objects will be prged if and when it is necessary to make room for newly arriving objects. The predetermined nmber is something yo can set yorself. Setting a large nmber allows Composer Enterprise Server to maintain many objects in memory, at the expense of available free Virtal Machine memory. Setting a low nmber means relatively few objects will be retained in memory, freeing p RAM. 127(A large cache does not garantee better performance: For example, rotine JVM garbage collection (compaction and prging of memory) becomes more timeconsming if the cache is large, and LRU analysis (and prning) of the cache is more costly as well. Yo will have to experiment with different cache settings to find the sweet spot for yor particlar prodction environment. The ser-adjstable parameters are as follows: Expression/XPath caching Enabling this option (radio btton ON) on means that Composer Enterprise Server will try to rese ECMAScript expressions and XPath objects at rntime whenever possible. Component Cache Expiry This setting allows yo to pt a maximm limit (in mintes) on the lifetime of inactive (bt still cached) xobjects. The defalt is 720 mintes (12 hors), which means no inactive component will stay in memory longer than 12 hors. (The key intition here is that if an object has been in memory for 12 hors and hasn t been sed, it probably doesn t need to be in memory any longer.) Total Component Cache Size This is the maximm nmber of Component objects that will be stored in the cache at rntime. Composer Enterprise Server Overview

22 The cache-expiry and total component size limits are enforced via a daemon process a cache prner that rns in its own thread. Every ten seconds, the prner inspects the cache to see if any objects have expired (reached their inactivity time limit, as discssed above), in which case those objects are smmarily prged from the cache, regardless of whether the cache is fll. The prner will also check to see if the cache has exceeded its Total Component Cache Size limit since the last inspection. If so, an appropriate nmber of least-recentlysed objects will be prged (regardless of whether those objects have timed ot) to adjst the cache size to stay within limits. Performance Tning Performance testing is a complicated sbject. No one piece of advice will be applicable to all sitations. Cache settings need to be determined empirically, throgh testing. Changes to cache settings made throgh the Composer Enterprise Server console do not necessitate a restart of the server. Bt yo may find that more generos cache settings take sch a toll on free memory that yo need to increase the amont of Virtal Machine memory allotted to Composer Enterprise Server. This is something that will necessitate a restart. To change the amont of memory allocated to Composer Enterprise Server, first sht down the server, then open the file called xconfig.xml, which is located in Composer Server s \lib directory (nlike the design-time Composer environment, where the xconfig.xml file is located in the \bin directory). In xconfig.xml, look for the element called VM_PARAMS. Change the settings here (that is, the content of the VM_PARAMS element) to reflect the starting and maximm RAM amonts yo wish to allocate to Server. (These are standard JVM command-line options. Conslt Sn s own docmentation for more information abot JVM lanch parameters and how to set them.) 127(Do not edit xconfig.xml while Composer Server is rnning. Composer will overwrite yor changes when it shts down. Always exit Composer and/or Server before editing xconfig.xml. Remember that generos cache and RAM settings do not necessarily eqate to better performance. The factors that determine performance are many, and have sbtle interactions. Yo will have to do carefl testing to determine the appropriate settings for yor particlar prodction environment. Composer Enterprise Server User s Gide

23 Updating Yor License Shold the need arise to pdate the license string associated with Composer Enterprise Server, yo can se the UpdateLicense.bat file (located in yor extendcomposer\bin directory) to accomplish this. From the command line, rn: pdatelicense prodct newlicense [Composer/Server] where prodct is the name of the particlar prodct (whose license yo wold like to pdate, newlicense is the license string, and the final argment (one of Composer or Server) specifies whether to pdate the design-time or rntime version of the prodct in qestion. Yo can see a list of installed prodcts by rnning: pdatelicense -L Composer Enterprise Server Overview

24 Composer Enterprise Server User s Gide

25 Planning Yor Deployment Chapter 3 Althogh, strictly speaking, it s not necessary to know how yo intend to deploy yor finished application before yo can begin designing it in extend Composer, it is always good practice to take deployment into consideration at the earliest possible stage in application design. (This is particlarly tre for large, complex applications and/or services that involve transaction management.) Before invoking the Deployment Wizard to create yor deployable objects, yo mst be prepared to specify how yor deployed application will be configred. For example, yo shold ask yorself: How is the service going to be instantiated? (E.g.: In response to an incoming URI with parameters? By another program?) What are the connection reqirements? (Will connection pools be reqired?) Do I need transaction control? (Will the transaction model be containermanaged, or bean-managed?) Which service trigger object model (EJB or Servlet) will be sed? Will services be located across mltiple machines? Do the service triggers reqire secrity constraints and/or specific role acess? Do my XML resorces (DTDs and XSL stylesheets) need to be accessible to my bsiness partners? Do I reqire access to special Java classes (cstom or existing)? Planning Yor Deployment

26 Instantiation of Services An Composer service may be deployed as a standalone entity that provides a complete bsiness process and simply needs to be instantiated to perform the bsiness process. Alternatively, the service may need to be integrated into a larger application. extend offers the flexibility to make that decision at the time of deployment, becase the services that are deployed act on XML docments withot needing to know the sorce of the XML. (See Chapter 4, Deploying a Project, for more information.) Web Services verss JMS Services Novell extend can create two types of services: the Web Service, and the JMS Service. (JMS stands for Java Messenging Service, a Sn API for integration of Java applications with message-oriented middleware.) Web Services are exected in response to XML data arriving via the World Wide Web (or via HTTP). JMS Services are exected in response to messages arriving at a message qee. Deployment considerations differ for the two service types. Web Services are dormant ntil invoked by a Service Trigger object, which is a servlet that responds to incoming HTTP data. Alternatively, a Web Service can be instantiated directly by another Java process rnning on the server. JMS Services, by contrast, are active from the time they are first deployed ntil the administrator trns them off. At deployment time, the JMS Service registers a MessageListener object with a message qee (or message topic) in a messageoriented middleware (MOM) environment. Once the JMS Service is listening on a qee, any arriving message will trigger the service s onmessage() handler, ths invoking the service. While Web Services are designed to handle XML inpt, JMS Services respond to messages, which can contain varios sorts of payloads (inclding XML, COBOL copybooks, and arbitrary byte streams). 127(The discssion of the JMS Service type applies only if yo have prchased and installed the extend JMS Connect. Withot this connector, it is not possible to create JMS Services. For more information on JMS Services, be sre to conslt the extend JMS Connect User s Gide. Composer Enterprise Server User s Gide

27 Standalone Deployment For standalone deployments, services are instantiated and perform all the reqired steps (e.g., convert inpt parameters to an XML string, perform any HTTP reqest necessary, log systems events, etc.) within the context of the extend Composer Enterprise Server. The Deployment Wizard will walk yo throgh the packaging of the project metadata and the creation of the Service Triggers based on how XML inpt will be received. For example, yo may need data from a Web page reqest with parameters or from a form, or yo may have information being sent to yo from a trading partner URI. The Deployment Wizard can atomatically create Service Triggers necessary to perform these types of processes. See Deployment Options on page 18 for more details on the options for yor deployment. 127(If the extend JMS Connect is installed, the Deployment Wizard will contain an extra panel pertaining specifically to deployment of JMS Services. The rest of the Deployment Wizard is the same for both service types. Integrated Application Deployment Some of the services yo create may need to be integrated into other applications. For this type of integration, yo may be able to se Service Triggers as described above or yo may wish to instantiate the service directly from a Java object in yor external application. To instantiate a service from a Java object, extend provides the JavaDoc API and referenceable sorce code for the extend Composer Enterprise Server framework (see Appendix C, Deployment Framework API Docmentation for details). 127(When deploying services that need to be integrated with external applications, yo need to be mindfl of proper JAR file packaging and CLASSPATH specifications. The xcs-all.jar file contains the classes reqired to execte the extend Composer Enterprise Server, and it reqires that both xconfig.xml and the project metadata be in the CLASSPATH. See Chapter 5, Programmatic Access to Composer Services for more details on the options for integrated application deployment. Planning Yor Deployment

28 Connection Pools Typically, when managing interactions with otside resorces, one of the most resorce consmptive operations is connection management. Allowing each transaction to open and close a connection for each reqest sally introdces significant application server overhead. To minimize this overhead, Server allows yo to exploit the connection pooling featres of yor application server. How Are Pools Identified? As mentioned, one of the services offered throgh the application server is database connection pools. In the Extend Application Server, these pools are identified by database name. The person responsible for the deployment of Composer projects into the application server mst nderstand how deployed services se transaction management. (See Chapter 6, Transaction Management for additional information.) The deployer also needs to nderstand the database accesses being performed in the service. To take advantage of Extend Application Server s connection pooling, the connection resorce for the target database mst have the pool name specified. Connectors For connections to non-database resorces, extend Composer Enterprise Server provides connection pooling capabilities that agment those of the application server. extend Composer Enterprise Server s connector-specific connection pools are configrable and manageable throgh separate extend consoles. To take advantage of connection pooling, see the Connect Gide for each type of connection being deployed (e.g., 3270, 5250, CICS RPC, JMS). Proxy Servers If yor service will be rnning inside a proxy server, yo will need to change certain settings in yor xconfig.xml file. At design time, yo can modify a project s proxy-server settings in extend Composer via the Tools/Configration dialog. (See the extend Composer User s Gide for details.) If yo have already deployed yor application or yo need to make last-minte changes to proxy settings withot the aid of Composer, open yor xconfig.xml file with a text editor and look for the PROXYSERVERINFO tag. The child elements nder this tag allow yo to fine-tne yor proxy settings. (Be sre the USEPROXYSERVER element is set to on if yor app will be rnning inside a proxy server.) Composer Enterprise Server User s Gide

29 Secrity Roles Roles provide a way for yo to stiplate access privileges to deployed extend Composer service triggers. The roles can be specified at deployment time and allow the administrator the flexibility to provide the actal secrity definition for the abstract role on the Application Server s console. With secrity roles, constraints can be placed on HTTP actions for particlar URL patterns. Pblishing XML Resorces When establishing a bsiness-to-bsiness process, yo may need to pblish certain files that are reqired by yor bsiness partners. Examples of these files inclde XSL style sheets for rendering an invoice and DTD/schema files for validating docments sent by yor site. For management and maintenance prposes, it is sally more effective to prepare these files in their own dedicated JAR and deploy them to the application server. A URI can then be associated with the JAR and its contents pblished. The se of special-prpose JARs can also be an effective strategy for resorce files needed by yor services, since they allow yo to deploy and maintain ancillary files (and the services that se them) separately. In creating special-prpose JARS, yo need to plan ahead and indirect all references to these resorces throgh extend Project Variables. Additional Java Classes Yo may find it convenient or necessary to integrate new Java classes into yor service. If yo do reqire additional Java classes in yor application, steps mst be taken to make them available (visible) to extend Composer and Server. (See the extend Composer User s Gide, Appendix A.) The main reqirement is that yo pt yor JARs into the Extend Application Server CLASSPATH.There are three ways to accomplish this: In Windows NT, select Start Settings Control Panel System Environment, or in UNIX modify the environment variable to set the AGCLASSPATH variable to inclde the necessary JARs or Add appropriate $SS_LIB entries in agjars.conf and copy the JAR files to the lib directory of the app server or Add classes directly to the server s application database Planning Yor Deployment

30 Composer Enterprise Server User s Gide

31 Deploying a Project Chapter 4 Deploying a project from extend Composer involves the following basic tasks: Determining the rntime context for the project s services. For example: Do yo wish to have yor services rn as standalone processes, or (alternatively) as part of another application? Is yor service a SOAP Service? A JMS Service? Creating deployment objects from Composer s Deployment Wizard Installing deployment objects into the extend Application Server Yor project can be deployed straight to the app server from Composer, or yo can inclde yor Composer project as a sbproject within a Workbench project. If yo deploy straight to the app server, yo ll be deploying a JAR. If yo package yor project into a Workbench project, yo will have the option of deploying in EAR or WAR forms. This discssion will focs mainly on JAR deployment. For detailed information on Workbench deployment of Composer projects, see the separate gide, ComposerAndWorkbench.pdf. Determining the Rntime Environment Before deploying an Composer project, yo mst decide whether the services will be execting standalone or integrated into another application on the application server. Deploying standalone services reqires the creation of Service Trigger objects, which extend Composer can create for yo atomatically as part of yor deployment, or which yo can create yorself. Integrating services into other Java applications reqires the se of the extend Workbench, which in its File > New > JSP, Java class, EJB, and Servlet wizards offers atomatic skeleton-code generation for varios kinds of triggers. Deploying a Project

32 Creating Deployment Objects A Composer project deployment may contain the following types of objects: Table 4-1 Object Use Notes: Project JAR File Servlets or EJB Service Trigger class files Deployment Descriptor Files (XML files with the same name as the Servlets or EJB Service Trigger files) Bild File SilverCmd batch file called ImportObjects. bat Deployment Profile file called xdeploy.xdp Contains the services, components and resorces of the project. Connects services to a Servlet or an EJB, prepares service inpt, and starts a service. Describes information necessary to install Service Trigger Java classes into the application server. The URI associated with the Servlet based Service Triggers and JNDI name for EJBs are described in these. Lists the Servlets to be bilt by the application server. Contains SilverCmd tility calls to install the deployment objects into the application server. Contains the deployment profile from the last time the Deployment Wizard was exected. XML resorces (DTDs, schema, XSL) can be deployed as resable resorces; see discssion later in this chapter. Reqired for standalone operation. Optional if services are to be integrated into another application throgh a cstom framework. Reqired if Servlets or EJBs are created. Prodced by Composer atomatically. Created atomatically. Created atomatically. Created atomatically. Allows extend to restore the previos deployment information the next time a deployment is performed. Composer Enterprise Server User s Gide

33 Composer s Deployment Wizard leads yo throgh the creation of all of these objects and atomatically installs the objects into the extend Application Server. The Deployment Wizard may be reexected at any time to change some or all of the options available or to re-deploy a modified project component. For a more detailed description of the contents of these objects, see Appendix B, Contents of Deployment Objects. Installing Deployment Objects There are two options for installing deployed objects into the extend Application Server. The first option is to have the Deployment Wizard atomatically install the objects after the necessary information for accessing the target server is spplied. The second option is to install the objects manally, sing tools like the extend Application Server s SilverCmd tility or the Novell extend Workbench IDE. Abot Service Triggers for Web Services Services are the primary nit of exection in the application server environment. All extend objects, inclding services, are created as metadata instrctions stored in XML files inside a deployment JAR. At deployment time, services need to be connected to their appropriate server triggering mechanism. The Deployment Wizard can generate two main types of Service Triggers for Web Services: Java Servlets and Enterprise Java Beans. In addition, the extend Composer Enterprise Server framework allows Service Triggers to be cstomized and created by hand. 127(The discssion abot triggers that follows applies to Web Services. JMS Services are invoked somewhat differently from Web Services. The same Deployment Wizard is sed for both kinds of services, however, since yo may have Web Services and/or JMS Services contained in a single deployable project. Servlet Based Service Triggers Java Servlets are sed as Service Triggers. They associate a URI with a particlar Composer service, convert inpt data from an HTTP Reqest into an XML docment that the service can accept as inpt and, finally, execte the service. Additionally, Servlets can be generated that indirectly trigger a service via an EJB. To trigger a service from an EJB, yo wold need to first generate the EJB based trigger (see EJB Based Service Triggers on page 34) and then generate the Servlet called by it. Deploying a Project

34 Servlet-based Service Triggers are created atomatically by the Composer Deployment Wizard. If necessary, these Servlet-based Service Triggers can be modified, or different ones can be defined than the ones created by extend. The following diagram describes several common scenarios for the Servlet types generated by the Deployment Wizard. EJB Based Service Triggers The second type of Service Trigger is an Enterprise Java Bean (EJB). EJBs are sed as Service Triggers for a variety of reasons, inclding flexible deployment and declarative transaction control. The generated EJB Service Triggers can be sed by any Java application to directly execte an Composer service. Invoking EJBs is not as straightforward as invoking servlets. For this reason, extend can generate Java Servlets of the types referenced in the preceding section to trigger EJB Based services. Servlet-to-EJB based Service Triggers split these tasks between two objects instead of one. A Servlet is sed to associate a URI, convert the inpt HTTP data to XML, then execte the EJB. The EJB, which mst reside on the same machine as the extend Project JAR, exectes the service. Composer Enterprise Server User s Gide

35 Application Based Service Triggers SOAP-Based Service Triggers As discssed previosly, an alternative to sing extend-generated Service Trigger objects is to create Service Trigger objects otside of extend or integrate Service Trigger fnctionality into another application that needs to se Composer services. Both of these application-oriented triggering options reqire se of the Composer Deployment Framework, which describes the interfaces to extend objects. See Chapter 5, Programmatic Access to Composer Services for more information. A specialized type of servlet trigger is Composer s SOAP-based trigger (which has its own panel in the Deployment Wizard; see frther below). If yo choose this type of trigger, Composer will generate a servlet that accepts incoming SOAP reqests via HTTP POST and nwrappers the SOAP body before handing it to yor service. Deploying a Project

36 JMS Service Triggers At deployment time, JMS Services instantiate a MessageListener object that registers an onmessage() handler with a message qee or message topic. The listener object for a JMS Service loads every time extend Composer Enterprise Server is rn (i.e., every time the app server is started), sbject to administrative control via a browser console. A JMS Service can also be deployed in sch a way that a given service relies on mltiple listener objects, with attendant gains in performance and bandwidth. Bt in any event, the service itself is not exected ntil a message arrives at the qee, at which time the onmessage() handler fires. Arrival of a message ths acts as a triggering event to which the service mst respond. Becase JMS Services have essentially infinite life and are active whenever the server is active, they mst be administered differently from other Composer services. A browser-based administrative console is provided for this prpose. See the extend JMS Connect User s Gide. 127(The above discssion is applicable only if yo have installed Novell extend JMS Connect. See the extend JMS Connect User s Gide for details. Using the Composer Deployment Wizard The Composer Deployment Wizard steps yo throgh a series of panels that prompt yo for information regarding varios characteristics of yor deployment. Some of the panels are optional and are clearly marked as sch. Others have fields that mst be filled ot. The wizard will alert yo if yo have not filled ot a reqired field. To se the Composer Deployment Wizard to generate the Project JAR, Service Triggers, and other deployment objects, select File, then Deploy from the Composer men bar. This will bring p the first panel of the wizard as shown below. The General Information Panel The first panel of the deployment wizard has the following appearance: Composer Enterprise Server User s Gide

37 Use this panel to specify general parameters for the deployment (described in additional detail below). If the project has previosly been deployed, then the vales sed in yor most recent deployment are displayed. Deployment Server Type Select the application server type for this deployment: Novell, IBM WebSphere, or BEA WebLogic. This configres Composer to create deployment files specific to the server environment selected. Deployment Staging Directory Specify the directory where yo want to place all the deployment objects created by Composer. Select the Browse btton to navigate to an existing directory or create a new directory. 127(Each project reqires its own directory. Deploying two projects to the same staging directory will case some deployment objects to be overwritten. If yo are redeploying a project bt have chosen an empty (new) directory for staging, yo will be prompted as shown below. Deploying a Project

38 Yo can, at this point, reset all fields in the wizard, or (alternatively) contine with the new deployment sing settings from the previos deployment. Project JAR Filename Enter the name for the JAR file that contains all the xobjects for this project. This file will then be created in the staging directory. Deployment Context in the Project JAR This context can be any name yo want. Enter a string, separating parts of the string with periods. The deployment context is sed to distingish two Composer services (in different projects) from each other shold they happen to have the same name, thereby preventing namespace collisions. 127(Do not se Java-langage keywords in yor context string. The complete list of reserved words is shown in the Reserved Words appendix. Composer Enterprise Server User s Gide

39 The Servlet Based Service Triggers Panel The second panel of the deployment wizard has the following appearance: Use this panel to select which Web Services will be deployed with Servlet-based Service Triggers. If the project has previosly been deployed sing the same staging directory, then the vales sed in yor most recent deployment are displayed. For each Servlet based Service Trigger being deployed, press the Add btton and specify the parameters below. Service Services from the project are displayed in the first field of each row. Select the service to deploy from the dropdown list that appears when yo click into the field. (All services in yor project will be shown in the list.) Deploying a Project

40 Servlet Type There are for Servlet types, representing the for ways in which a Composer service can be passed data: Params (URL/Form), XML (MIME mltipart), XML (HTML form field), and XML (HTTP POST). Each Servlet Type differs in the manner it accepts inpt data. The differences are smmarized in the table below. Servlet Type Accepts Data Via Notes Params (URL/Form) XML (HTTP POST) XML (MIME mltipart) URI Parameters appended to the URI in rlencoded form Posted XML Docment Content. (e.g., XML Interchange Action - Post). XML File from an HTTP mltipart/form data post method. (This allows a ser to browse their file system and pick the XML file to sbmit.) This Servlet bilds an inmemory XML docment sing HTTP URI form parameters as the names of nodes and their vales as text. Mltiple vales for a parameter can be handled, bt mltiple inpt docments are not created. This Servlet extracts an XML docment sent via an HTTP POST method. This differs from HTML Form POSTs that contain parameter name vale pairs. The payload of this kind of HTTP transmission is, in fact, the raw XML docment. It is a convenient method for exchanging XML docments with trading partners. This Servlet extracts a service s inpt docment from a mltipart encoded form containing a field with an inpt type of file. The Servlet expects the field name containing the XML file to be called xmlfile and it ses the first occrrence of this parameter for the extraction. Composer Enterprise Server User s Gide

41 XML (HTML form field) XML inside a POSTed form. The XML mst be inside a field labeled xmlfile. This Servlet extracts a service s inpt docment from a POSTed form s field. The Servlet expects the field name containing the XML file to be called xmlfile and it ses the first occrrence of this parameter for the extraction. Otpt Type Select XML or HTML via PI from the plldown men, as appropriate to yor service s otpt. Use HTML via PI if yor Web Service will be otptting HTML as a reslt of applying an XSL stylesheet (via a Processing Instrction) to yor XML data. This will ensre that extend sets the correct MIME type for yor otpt. Role Enter the name of a J2EE role that will be allowed access to the service trigger. Only the individal or members of the grop that are mapped to the entered role name will be able to access the service trigger. Yo will need to ensre that yo create a server grop that matches the name of the role, to be able tilize the role access capabilities. Defining a secrity role is optional. If yo do not reqire access restrictions leave the Role field blank. URI Path The URI Path provides a niqe name for the URI that is assigned to this Servlet. This name, together with the Novell extend server name and database name, makes p the fll URI to access this Servlet. For example, if the URI Path is specified as WebStore/ProdctInqiry, and the server name is strats, and the database name is InfoDB, then the fll URI will be: Deploying a Project

42 The EJB Based Service Triggers Panel Use this panel to select which services to deploy with EJB based Service Triggers. If the project has previosly been deployed sing the same staging directory, then the vales sed in yor most recent deployment are displayed. For each EJB based Service Trigger being deployed, click the Add btton and specify the parameters below. Service JNDI Path Transaction Attribte Choose a service from the dropdown list that appears when yo click into the Service field. The list will be poplated with the names of services contained in yor project. The JNDI Path provides a niqe name that is sed to locate the EJB. This name together with the initial context string sssw://, and the Novell extend server name, and the string RMI, make p the fll JNDI compond name to locate this EJB. For example, if the JNDI Path is specified as WebStore/ProdctInqiry, and the server name is strats, and the JNDI Service Provider is RMI, then the fll JNDI Name will be: sssw://strats/rmi/webstore/prodctinqiry. Select an EJB Transaction Attribte to apply to the Container, if desired, from the plldown men. Otherwise, choose Not Spported. Composer Enterprise Server User s Gide

43 The Servlet-to-EJB Triggers Panel This panel will appear only if yo added one or more entries to the preceding panel; otherwise yo will be taken directly to the SOAP Trigger panel (see next section). Use this panel to set p Servlet invocation of yor EJB based Service Triggers. As discssed in the section Abot Service Triggers, Servlet - EJB based Service Triggers se two objects to handle the triggering fnctions of URI association, inpt conversion to XML, and starting the service. The EJB handles starting the service while a Servlet on the front end handles URI association, inpt conversion and firing of the EJB. If the project has previosly been deployed sing the same staging directory, then the vales sed in yor most recent deployment are displayed in the following panel. For each Servlet EJB based Service Trigger to be deployed, click the Add btton and specify the parameters below. EJB Service EJB based Service Triggers defined on the previos panel are displayed in the first field of each row. Select the EJB based Service Trigger by its JNDI Path, sing the dropdown list that appears when yo click into the field. Deploying a Project

44 Servlet Type There are for Servlet types: Params (URL/Form), XML (MIME mltipart), XML (HTML form field), and XML (HTTP POST). Each Servlet Type differs in the manner it accepts data intended as inpt to a Service. These differences are smmarized in the table in the previos section on Servlet-Based Service Triggers, frther above. Otpt Type Select XML or HTML via PI from the plldown men, as appropriate to yor service s otpt. Use HTML via PI if yor Web Service will be otptting HTML as a reslt of applying a stylesheet (via a Processing Instrction) to yor XML data. This will ensre that extend sets the correct MIME type for yor otpt. Role Enter the name of a J2EE role that will be allowed access to the service trigger. Only the individal or members of the grop that are mapped to the entered role name will be able to access the service trigger. Yo will need to ensre that yo create a server grop that matches the name of the role, to be able tilize the role access capabilities. Defining a secrity role is optional. If yo do not reqire access restrictions leave the Role field blank. URI Path The URI Path provides a niqe name for the URI that is assigned to this EJB trigger Servlet. This name, together with the Novell extend server name and database name, make p the fll URI to access this Servlet. For example, if the URI Path is specified as WebStore/ProdctInqiry, the server name is strats, and the database name is InfoDB, then the fll URI will be: The SOAP-Based Triggers Panel Use this panel if yo wold like to specify that yor Servlet-based triggers know abot SOAP wrappering of incoming data. Composer Enterprise Server User s Gide

45 Service Click the Add btton to add services to the list. For each, in the Service field, choose a service from the dropdown list that appears when yo click into the field. SOAP Bind Style SOAP allows for RPC-style or Docment-style messages. Choose rpc or docment from the dropdown men. See for additional information on these options. Body/Namespace This is where yo can specify the namespace prefix that will be assigned to the message contained in the SOAP body. URL Path In this field, specify a URL alias that will point to the generated servlet. Role Enter the name of a J2EE role that will be allowed access to the service trigger. Only the individal or members of the grop that are mapped to the entered role name will be able to access the service trigger. Yo will need to ensre that yo create a server grop that matches the name of the role, to be able tilize the role access capabilities. Deploying a Project

46 Defining a secrity role is optional. If yo do not reqire access restrictions leave the Role field blank. The Resorces Deployment Panel Use this panel if yo wold like to deploy project resorces (sch as WSDL or XSD files) in sch a way that they can be accessed via a pblic URI. First, check the checkbox called Provide Resorces. This will enable the Relative URL field. In that field, enter the URI fragment (relative to yor host pathname) that points to yor resorce chain. Then choose the resorces that yo want to deploy from the list on the left and transfer them to the list on the right sing the transfer bttons in the center of the dialog. Optionally, enter the name of a J2EE role that will be allowed access to the service trigger. The Relative URL is relative to the host part of the URL. The host part is the same URL as yo will later enter in the top text field of the final panel of the Deployment Wizard (see frther below). Yo do not need to enter this root URL in the dialog shown above. The portion yo need to enter nder Relative URL is simply the resorce directory (or sbpath) leading to the resorces shown in the above picklists. For example, if yo are serving from and yor resorces will be at /resorces/soap, enter that into Relative URL. Then if yo choose to make wsdl/soap-wsdl available as a pblic resorce (as shown in the screen shot above), it will be available at: Composer Enterprise Server User s Gide

47 The Project Variable Remapping Panel Use this panel if yo wold like to change the vales of project variables for prposes of deployment. At design time, yo may have defined project variables that point to work files located on a development drive or directory. For prposes of final deployment, yo may wish to give those project variables new vales based on the server location(s) of actal deploy-time resorces. This panel allows yo to do that. 127(Project variables are stored in the PROJECT.xml file (in the same directory as yor project s.spf file). If yo change project variable vales sing this panel, the PROJECT.xml file that gets written to the server will differ from the PROJECT.xml file in yor working directory. This is normally what yo want. The JMS Service Trigger Panel If yo have installed the JMS Connect and yor project contains one or more JMS Services, yo will see the JMS Service Trigger panel (shown below). If yo wish to deploy JMS Services, click the Add btton, then select a JMS Service from the plldown men nder JMS Service. Next, enter a text description to the right of it. Then enter a Cont vale to indicate how many concrrent listeners yo want to deploy. Deploying a Project

48 Add as many JMS Services as yo want to deploy, by clicking the Add btton repeatedly. When yo are finished, click Next to go to the final panel of the Deployment Wizard. The Atomatic Installation Panel The final panel of the Deployment Wizard is shown below. Use this panel to: set a server name and port set the server database spply server sername and password information determine if the Deployment Wizard shold atomatically pload and install yor deployment objects to the extend Application Server (or not) As with all panels in the wizard, if the crrent project has previosly been deployed sing the same staging directory, then the vales sed in yor most recent deployment are displayed in this panel. Composer Enterprise Server User s Gide

49 Novell extend Server and Port Enter the name and port nmber of the Novell extend server to receive the deployment objects. Novell extend Database Name Enter the application database name that registers the deployment objects. User Name and Password Enter a valid User Name and Password for the application database if reqired. Administration of Deployed Projects Administration of deployed projects takes place throgh console pages displayed in a web browser. See Administrative Control of Composer Enterprise Server on page 19 for more information. Deploying a Project

50 Installing Deployment Objects Using SilverCmd This section describes how to bild a set of files to deploy an Composer project and spporting Service Triggers into a extend Application Server sing the SilverCmd command-line tility that ships with extend Application Server. The Composer Deployment Wizard normally deploys projects atomatically, bt yo may have special circmstances that reqire manal deployment of yor project. For manal deployment, se the SilverCmd tility as otlined in this section. 127(The following discssion is not intended to serve as definitive docmentation for the SilverCmd tility. For more complete docmentation of SilverCmd, conslt the online reference gide to SilverCmd, located nder help/books/toolssilvercmd.html in yor Novell extend Docs folder. The extend Application Server ses an object repository to store its Servlets, Web pages and other application resorces. A command line management tility, SilverCmd, is provided for installing application resorces created otside of the Novell extend IDE. SilverCmd ses XML files to describe the deployment entities and isse simple instrctions to define whether sorce code class files are being imported, or whether to bild sorce code within the Novell extend environment. SilverCmd offers significant fnctionality for application deployments, making it the ideal tool to se to manally deploy Composer applications and spporting resorces into a extend Application Server. Some reasons to consider creating SilverCmd batch and descriptor files: To add Java classes to interact with the deployed Composer service components To deploy an XML resorce JAR file for pblishing XSL stylesheets, DTDs and XML schema ½ To install deployment objects into the Novell extend server: Assemble deployment related files. Create SilverCmd description files for the deployment related files. Install the objects sing SilverCmd. 127(exteNd Composer can perform all three steps atomatically. Composer Enterprise Server User s Gide

51 SilverCmd Instrctions The best way to begin a manal deployment is by creating a main batch file that contains all of the SilverCmd instrctions to import and initialize deployment objects. Create a file that contains a SilverCmd instrction for each object that is reqired to spport the Composer service component. Normally, when extend Composer creates the deployment files in the staging directory, the name of the main batch file that contains all of the SilverCmd instrctions that are reqired is called ImportObjects.bat. The types of instrctions that can typically be sed are as follows: Import Java sorce files Bild Java sorce files Import Java class files Import Composer project JAR files Import EJB deployment JAR files Deploy EJB JAR files Import XML resorce JAR files Import Java Sorce Files The sorce files contain the implementation of a Novell extend-triggered bsiness object, which interacts with an Composer service component. Examples of types of triggered objects are: Servlet Invoked Data Sorce Table-modified Mail Schedled Fll explanations of these and other triggered bsiness objects can be fond in the extend Application Server Help, Programmers Gide, Developing Triggered Bsiness Objects. The sorce files are imported bt are not sable ntil they are compiled in the Application Server. This means that for each sorce file that is mentioned in the ImportObjects.bat file, there will need to be an eqivalent entry in the bild instrctions descriptor file. The advantage of importing the sorce code for a triggered bsiness object is that the sorce is available for modification or reference from within the Novell extend Composer IDE. Deploying a Project

52 These entries reqire a descriptor file that provides vales for the triggered bsiness objects reqired parameters. For example, a mail-triggered object wold have a descriptor file that contains the mail accont name and the object s lifetime. A Servlet triggered object wold have a descriptor file that contains a list of URI aliases for the Servlet and the object s lifetime. The typical syntax for importing the sorce file wold be: Where: SilverCmd ImportSorce server[:port] database javafile f descriptorfile o javafile The name of the Java sorce file. -f Specifies an inpt file (given by descriptorfile) descriptorfile The name of the file containing the parameters specific to the type of triggered bsiness object that the sorce is implementing, as well as the Composer project JAR file association. -o Specifies that an existing copy of the file shold be overwritten by this import. Bild Java Sorce Files For any Java sorce files that are imported into the extend Application Server, it is necessary to explicitly instrct the server to compile the Java files into sable objects, or class files. This instrction reqires a descriptor file containing the names of the sorce code files to be compiled. An entry shold appear in the descriptor file for each imported sorce file. The typical syntax for bilding sorce files is: Where: SilverCmd Bild server[:port] database f descriptorfile -f descriptorfile The name of the file containing the list of objects to bild. Import Java Class Files Used to bild the Novell extend triggered bsiness objects sing an external compiler and import the class files only with no sorce. This instrction reqires a descriptor file if the class is a triggered bsiness object. While the descriptor file contains bsiness object specific parameters, it also contains the association to the project JAR file. The typical syntax sed for importing the class files is: Composer Enterprise Server User s Gide

53 Where: SilverCmd ImportClass server[:port] database classfile f descriptorfile classfile The name of the Java class that is imported. -f descriptorfile The name of the file that contains the bsiness object specific parameters, as well as the Composer project JAR file association. Import extend Project JAR Files The JAR file that contains the extend-deployed project can be imported as a media file sing the SilverCmd tility. Since the JAR file is bilt otside of the Novell extend Composer IDE, the contents of the JAR are not viewable withot exporting it from the application server. The typical syntax for this instrction is: Where: SilverCmd ImportMedia server[:port] database jarfile o jarfile The name of the Composer project JAR file to import. -o An option to indicate that a JAR file of the same name shold be overwritten by this import. Import EJB Deployment JAR Files Cstom developed EJB s that tilize the extend Composer Enterprise Server framework reqire an EJB deployment JAR file. The JAR file contains the class files that make p the EJB and a deployment descriptor called meta-inf/ejbjar.xml. The deployment descriptor contains entries that describe all of the EJB s with the following information: Type of EJB: Session or Entity bean EJB Class name Home interface name Remote interface name State management type: Statefl or Stateless. Transaction type: Bean managed or Container managed. Conslt the extend Application Server Help, Programmers Gide, Developing Enterprise Beans, Understanding Deployment Descriptors to get a fll description on what shold appear in the deployment descriptor. Deploying a Project

54 The SilverCmd instrction that is sed to import the JAR file is ImportMedia. It does not reqire a SilverCmd descriptor. Once the JAR file is imported, it still needs to be deployed before any of the EJB s contained within it are sable. The typical syntax for this instrction is: Where SilverCmd ImportMedia server[:port] database ejbjarfile o ejbjarfile The name of the EJB deployment JAR file to be imported. -o An option to indicate that a JAR file of the same name shold be overwritten by this import. Deploy EJB JAR Files For each EJB deployment JAR file imported into the extend Application Server, there is a final step of deploying the EJB JAR. The SilverCmd instrction to do this is DeployEJB. This instrction reqires a descriptor file that contains parameters to set the JNDI name for each bean that is being deployed. It is also possible to stiplate that the EJB s are associated with the Composer project JAR file. The typical syntax for this instrction is: Where: SilverCmd DeployEJB server[:port] database ejbjarfile f descriptorfile ejbjarfile The name of the EJB JAR file on the extend Application Server that is deployed. -f descriptorfile The name of the file that contains the parameters necessary to deploy the EJB s. Pblishing XML Resorces in the Application Server XML resorces are the DTDs, schemas and XSL style sheets associated with a project. In many cases it is necessary to pblish these resorces on the application server. Composer Enterprise Server User s Gide

55 Deploying XML Resorce JAR Files XML resorce JARs make it possible for yo to pblish XML resorces that have pblic URIs sing yor own pathnames. To take advantage of this mechanism, first create a JAR which contains the XML resorces (DTDs, XSL, and so on). Then se the SilverCmd instrction DeployJSP to pload the resorce JAR file. The syntax is: SilverCmd DeployJSP server[:port] database jarfile -f descriptorfile Where: jarfile The JAR containing yor XML resorces. -f descriptorfile Specifies the file containing URI associations. (See deploy_jsp.dtd and deploy_jsp_sample.xml in the /DTDs directory for information abot how this file shold be strctred.) Deploying a Project

56 Composer Enterprise Server User s Gide

57 Programmatic Access to Composer Services Chapter 5 The deployment of Composer services sing the Deployment Wizard (as described in the last chapter) is appropriate for cases where yo are interested in allowing network access, via HTTP, to Composer services that perform straightthrogh processing fnctions in more-or-less standalone fashion. Bt in many cases, yo ll be more interested in bndling Composer services into large, potentially complex J2EE projects that reqire specialized coordination between exectable objects. These kinds of projects may reqire tight integration between objects from a packaging point of view (WAR file, EAR File) as well as a rntimeexection point of view. To achieve yor integration goals, yo may find it sefl to create yor own cstom trigger objects for invoking Composer services. Yo can create cstom triggers in two main ways. One way is to se the extend Workbench to create servlet code, JSP pages, or cstom Java classes that can invoke yor Composer services. (The Workbench has bilt-in wizards aimed specifically at generating Composer-oriented code. Also, the Workbench offers flexible options for packaging yor code into WAR, EAR, and JAR files and deploying those objects into the prodction environment.) The other way to approach cstom trigger code development is to se yor favorite Java IDE to create code that calls on Composer s Framework Objects (which are inclded with Composer Enterprise Server). The se of Framework objects affords a lowlevel approach to creating trigger code. No matter which development rote yo choose, it s important to have a good nderstanding of the mechanics of instantiating and calling Composer services. Therefore, we ll begin by looking at the Framework architectre and how to se the Framework API. Later, we ll show how to se extend s Workbench as a rapiddevelopment aid for creating cstom Java code and JSP pages that can invoke Composer services. Programmatic Access to Composer Services

58 Extending Composer s Service Trigger Hierarchy To simplify the manal creation of extend s deployment objects, Novell provides a set of framework classes that can be sed to create Service Triggers for Composer services. Yo will find the framework files in the \docs\api\com\sssw\b2b\xs path nder yor Extend Application Server installation. Also, JavaDoc files will be fond nder this path and will be generated here if yo choose to create yor own JavaDocs. For detailed class descriptions, conslt the JavaDoc files. Only a brief overview will be given here. Service Component Names within Framework Objects When referring to a service component name within a framework object (e.g., Servlet), combine the deployment context with the service component name (see Creating Deployment Objects on page 32). The following is an example of a flly qalified service name: Where: com.yorcompany.project.prodctinqiry com.yorcompany.project is the deployment context specified dring deployment ProdctInqiry is the Composer service component name Deployment JARs contain one or more Composer services. Service Triggers are the brokers between reqests received by the application server to start an Composer service. For each deployment method, helper classes are provided that give yo extra fnctionality for integrating services into cstom applications. The relationships of varios framework components are shown in the graphic below. Composer Enterprise Server User s Gide

59 How to Create Service Trigger Extensions Service Triggers are classes that retrieve inpt XML docments from their environment and execte an Composer service component, retrning an otpt docment back to the calling client. The main service trigger that is ½ To create Service Trigger extensions for Web Services: Create a Java object derived from an Composer Deployment Framework object sing Novell extend Workbench or any other Java development environment. Import the object if Composer was not sed to create it. Compile the object. The extend framework contains abstract classes that provide base fnctionality for the basic type of Service Triggers, based pon Java Servlets. Programmatic Access to Composer Services

60 Creating Servlet-Based Service Triggers The hierarchy for Servlets is based on one abstract class derived from HttpServlet. The abstract class called GXSServiceRnnerEx, which derives from HttpServlet, contains the logic needed to: Recognize the Composer service component that all reqests will be exected against by calling the abstract method getservicename(). Call the abstract methods processreqestex() before, and processresponse() after, execting the service component. To extend the framework, and create yor own trigger type, yo mst create a converter object that can translate an HttpServletReqest into an XML inpt docment. To do this, yo will create a class that implements the IGXSInptConversion interface. Yor class mst implement the abstract method processreqest(). Any class implementing this interface will also need to define a constrctor that takes an IGXSServiceRnner as a parameter, so that the service rnner s varios getter methods can be called in order to retrieve properties. (The information determining what inpt type is accepted and whether the service will be invoked from a servlet or an EJB is contained in service properties. See table below.) Service Property Name Description Initialization Parameter GXSServiceRnnerEx method SERVICE_NAME The name of the Composer service component. servicename getservicename() ROOT_NAME The root node that is expected as the inpt docment. rootname getrootname() JNDI_NAME The JNDI name of the EJB home interface, for the Composer service component. jndiname getjndiservicename() CONVERTER_ CLASS_NAME The class that shold be sed to convert the HTTP reqest into an XML docment. converterclassname getconverterclassname() PARAM_NAME The name of the parameter that contains the inpt XML docment. xcs_paramname getxcsparamname() Composer Enterprise Server User s Gide

61 SERVICE_TYPE Whether the service component reference is an EJB or NORMAL. xcs_servicetype getservicetype() PROVIDER_PARAM The JNDI provider URI. provideruri CONTEXT_FACTORY The JNDI context factory. contextfactory HTML_INDICATOR An indicator sed to specify whether the otpt docment will be rendered as HTML. transform_into_html getotpthtmlindicator() OUTPUT_XSL If the otpt docment is being transformed into HTML, this will give the URI of the style sheet. This is only necessary if the XSL processing instrction has not been imbedded in the otpt XML docment. otpt_xsl_uri getotptxsl() The GXSServiceRnnerEx class needs to provide an implementation of the following methods: getservicename() method to bind the Servlet to the Composer service component a getrootname() method to retrn the name of the in-memory DOM a getservicetype() method that retrns a string vale of NORMAL or EJB, indicating the type of service component that will be invoked a getconverterclassname() method that retrns the name of the class that implements the IGXSInptConversion interface a getotpthtmlindicator() method that retrns tre if the otpt of the service will be HTML and false if it will be XML. An example of a converter class is shown below. pblic class mygxsinptfromhttpparams implements IGXSInptConversion { // Attribte that holds the service // rnner for qerying parameters. IGXSServiceRnner mrnner = nll; // Constrctor to take the IGXSServiceRnner // so that the class can retrieve params pblic GXSInptFromHttpParams( IGXSServiceRnner arnner ) Programmatic Access to Composer Services

62 { } mrnner = arnner; } // the processreqest method shold take // an HttpServletReqest as // a parameter and retrn an XML doc as a String: pblic String processreqest( HttpServletReqest areq ) throws GXSConversionException { String lsexpandeddoc = nll; // ( create DOM... ) retrn lsexpandeddoc; } GXSServiceRnnerEx A short description of the abstract processreqestex() method of the GXSServiceRnnerEx class follows. String[] processreqestex( HttpServletReqest ) This is a method that receives the crrent Servlet reqest (which in trn holds the parameters and other data passed to the Servlet by the reqesting client). The method mst retrn a String arraycontaining an XML docment that will be sed when execting the Composer service component that the Servlet is bond to. While processing the reqest, if there is no information with which to bild an XML docment, retrn an empty String and the Composer service component will behave as if there were no inpt XML docment. Creating Cstom Servlet EJB Based Service Triggers An EJB provides a way to ensre that connection pooling, transactions and persistence are atomatically managed by yor application server. As stated earlier, Servlet and EJB-based Service Triggers can be combined, providing a robst and flexible deployment model (e.g., extend Web Services and Servlet Triggers residing on different servers). The starting point for EJB-based Servlet triggers is GXSServiceRnner, which contains a getter method to inspect the SERVICE_TYPE property (which will be EJB in the case of a bean-based service). The service component is the GXSEJBService, which can only be instantiated by sing the GXSServiceFactory helper class. Composer Enterprise Server User s Gide

63 To extend the framework and create yor own EJB trigger type, yo mst provide a converter object that can translate an HttpServletReqest into an XML inpt docment. To do this, yo will create a class that implements the IGXSInptConversion interface. Yor class mst implement the abstract method processreqest(). Any class implementing this interface will also need to define a constrctor that takes an IGXSServiceRnner as a parameter, so that the service rnner s varios getter methods can be called in order to retrieve properties. The class shold be packaged in a separate library. This packaging allows for the creation of simple deployment-time Service Triggers that inherit from the new Service Trigger template. All that the deployment-time Service Trigger needs to provide is an implementation of the getjndiservicename() method to bind the EJB-based Servlet to the Composer service component. Creating Service Triggers From Scratch What Is Available in the Framework The extend Composer Enterprise Server framework provides all the factories and interfaces to allow the integration of an Composer service with Java classes. The framework provides a straight-forward interface that represents an Composer service. It also provides a set of static methods within a factory class to help instantiate the object that represents the Composer service. The extend Service Interface: IGXSServiceComponent The main Java element that allows for the exection of Composer services is the interface called IGXSServiceComponent, which is fond in the com.sssw.b2b.xs package. The interface provides for execte() methods that accept and retrn a variety of parameters. Once the interface is instantiated and with an inpt docment in one of the three forms, the Composer service can be exected and retrn its otpt docment. The extend Service Factory: GXSServiceFactory Within the framework there is a factory class called GXSServiceFactory. This class removes the complexities associated with creating an Composer service. It also provides some conversion methods to provide better flexibility when dealing with inpt and otpt docments from Composer services. Programmatic Access to Composer Services

64 To instantiate a new service interface, call the factory s createservice() method. Spply the qalified name of the service in a string. The following example exectes an Composer service called ProdctInqiry with a deployment context of com.acme.inventory. pblic void dosomething() throws GXSException { String servicename = "com.acme.inventory.prodctinqiry"; String inptdoc = ""; String otptdoc = nll; IGXSServiceComponent myservice = nll; // set the inptdoc to a valid XML docment format // that yor service expects. myservice = GXSServiceFactory.createService( servicename ); otptdoc = myservice.execte( inptdoc ); } // Do something with the otpt docment. retrn; Utilizing Service EJBs In an Application As the enterprise reqirements grow and distribted applications become a necessity, it may be necessary to deploy Composer services as EJBs. When developing applications to se these remote services, se the EJB remote interface in place of IGXSServiceComponent. Setting Up Yor Development and Rntime Environment Since the Composer service is deployed as an EJB on a Extend Application Server, ensre that the development and rntime environments inclde the necessary Novell JAR files. A fll list of the reqired JAR files can be fond in the Extend Application Server Help, Programmers Gide, Developing External Java Clients, Deploying Yor Client. Novell extend Application Server ses JBroker for RMI capabilities. The JRE fond within the Novell program directory contains properties that are essential for the application to sccessflly tilize EJBs. Composer Enterprise Server User s Gide

65 Getting the EJB Home and Remote Interfaces The EJB remote interface, called IGXSEJBServiceComponent, is located in the com.sssw.b2b.xs.ejb package. When deploying an Composer service as an EJB, add an environment setting called servicename. The EJB will look p the environment reference to see which Composer service it will be bond to. Also, at EJB deployment time, assign a JNDI name to the EJB. It is this name rather than the qalified Composer service name that will be sed to get a reference to the EJBs home interface. The name of the Composer service s EJB home interface is IGXSEJBServiceHome. When specifying the JNDI name for an EJBs home interface remember that, for the Extend Application Server, the string sssw://host/rmi/ is prepended. For example, if yo were deploying an EJB into a Extend Application Server called main.server, the JNDI name for the EJB is com/acme/inventory/prodctinqiry, the flly qalified JNDI name wold be sssw://main.server/rmi/com/acme/inventory/prodctinqiry. Once the home interface has been retrieved, mch like the GXSServiceFactory s createservice() method, a method called create() can be invoked which will retrn the remote interface of the EJB. The remote interface contains two execte methods. One takes no parameters and shold be sed if yo know that the Composer service does not take any inpt docments. The second takes an XML docment as a string. Yo will notice that the Reader or Docment versions available in the IGXSServiceComponent are not available in the EJB remote interface. This is becase none of those types is serializable and ths none is able to appear in a remote method. Factory to Obtain EJB Home Interfaces To make things a bit simpler, there is a factory class called GXSEJBAccessor, located in the com.sssw.b2b.xs.sssw package. It contains two methods to obtain an EJB s home interface from a Extend Application Server. One method can be sed within a server that does not reqire athentication; the second provides two extra parameters for sername and password. When sing the factory, there is no need to flly qalify the JNDI name assigned to the EJB. The factory creates the flly qalified hostname with the spplied parameters. In the following example, the JNDI name of the EJB is com/acme/inventory/prodctinqiry, the Extend Application Server name is main.server and the ports are at their installation defalt of 80 for HTTP and for RMI. import com.sssw.b2b.xs.ejb; import com.sssw.b2b.xs.sssw.gxsejbaccessor; Programmatic Access to Composer Services

66 pblic void dosomeejbstff() throws java.rmi.remoteexception { IGXSEJBServiceHome srvchome = GXSEJBAccessor.getHomeBean( com.sssw.b2b.xs.ejb.igxsejbservicehome, com/acme/inventory/prodctinqiry, main.server, 80, ); IGXSEJBServiceComponent ejbsrvc = srvchome.create(); // Do something with the service component } Using the extend Workbench to Create Cstom Triggers The extend Workbench has a nmber of bilt-in wizards that can help yo in creating some of the kinds of code described above. For example, the Workbench can lead yo throgh the creation of JSP pages, cstom servlets, and cstom Java classes that instantiate and se Composer services. These wizards, and how to se them, are described in detail in an accompanying gide, ComposerAndWorkbench.pdf, which yo will find in yor Composer docmentation folder. Composer Enterprise Server User s Gide

67 Transaction Management Chapter 6 Composer applications that perform transactions reqire special planning and deployment. The isses associated with transaction management are covered in this chapter. Transaction Control in extend Composer In extend Composer, the Transaction action can call any of the defined Java Transaction API (JTA) server-side transaction commands. For example: The begin, commit, and rollback commands are available for se in projects that will be deployed as servlets or as bean-managed EJBs. The Set Rollback Only command is available for se in projects that will be deployed as container-managed EJBs. These choices, appropriately enabled/disabled, are available from the Transaction dialog (see below), which appears when yo create a new Transaction action in Composer. Transaction Management

68 Transaction Deployment Considerations for the Extend Application Server As described in earlier chapters, the two bilt-in Service Triggering Mechanisms for Composer projects are Servlet and Enterprise Java Bean (EJB). Each mechanism has important implications for transaction control, as a reslt of the way transactions are defined in the Java Transaction API (JTA). Servlet Deployment Considerations Servlet deployment sing JDBC connection pools are recommended when complex transactional behavior is not reqired, sch as inqiry-only services. The primary limitations of Servlet deployments are: Declarative transaction control is not allowed. If this is a reqirement, se an EJB deployment instead. JDBC connections from the connection pool destined for a Servlet are by defalt set with ato-commit trned on. This means that after each Update, Delete, or Insert statement, the transaction is atomatically committed to the database. Sbseqent rollbacks will have no effect. There are two ways to change this behavior: 1. Isse a Begin Transaction command (sing a Transaction action), and tilize a sbseqent Commit or Rollback command as appropriate. 2. Check the Allow SQL Transactions checkbox for the connection. See JDBC Transaction Control: Allowing User Transactions on page 71 for frther details. 127(Nested transactions are not allowed, bt seqential ones are. EJB Deployment Deploying Composer services as EJBs gives the maximm transaction management flexibility. EJBs are the recommended deployment choice if yor application reqires a distribted transaction environment where data has to be pdated in a nmber of back end systems. Before examining extend specifics for EJB Deployment, it is worthwhile to review the deployment options regarding transactions as indicated in the EJB specification. The following definitions are helpfl: Application is the ser of the transaction services, normally the EJB. Container is the application server provided context in which an EJB is deployed to and exectes. Composer Enterprise Server User s Gide

69 Resorce Manager is the interface to the back end system, sch as a database or a message qee. Resorce Adapter is the interface to the Resorce manager, sch as a JDBC driver. Transaction Manager is an application server provided object that controls the flow of the transaction, setting p the transaction between all players. This normally involves mapping the high level calls to low level transaction calls to the standard X/Open XA protocol. See the accompanying illstration. All container-managed transactions are on a method call basis, while statefl Bean-managed transactions may span method calls. The EJB literatre sometimes implies that with EJBs, all transaction management is done behind the scenes and is of no concern to the application developer. Althogh complex two-phase commit logic is, in fact, performed atomatically (and rollbacks will atomatically occr if exceptions are thrown), developers still need to have an nderstanding of how EJB transactions are managed in order to ensre desired application reslts. Bean Managed Transaction Demarcation When an EJB is deployed as a Bean-managed transaction, it is expected to commnicate with the transaction manager indirectly via a simplified transaction interface called UserTransaction. UserTransaction provides transactional commands sch as begin, commit, and rollback. These commands are only available to the Bean if it is deployed as Bean-managed. If they are issed when the EJB is deployed as Container-managed, an IllegalStateException is thrown. Conseqently, developers need to know in advance how the Bean is going to be deployed. Transaction Management

70 Container-Managed Transaction Demarcation Container-managed Transaction demarcation, also known as declarative transaction spport, is a powerfl and flexible means for transaction spport. The application assembler is free to determine the EJB s transactional behavior post constrction. Container-managed transactions are most sefl in cases where EJBs tilize other EJBs to get work done. The classic example of this case is a stateless Session Bean calling several Entity Beans to pdate varios tables in a database. Linking their transaction via declarative transaction management greatly redces the complexity of the code, as any failre in any of the components can atomatically roll back the transaction. EJBs spport six different Container-managed transaction types. The most important differentiator among the six is the notion of transaction propagation. If one EJB with an ongoing transaction calls another, the transaction may or may not be passed along to the second EJB. If it is passed, and the transaction is sbseqently rolled back, then all work done in all EJBs within the scope of that transaction are rolled back. Container-managed transaction types inclde: Table 6-2 Transaction type Not Spported Reqired Spports Reqires New Mandatory Never Behavior No transaction spport is available. If called with a transaction, it will join, else it will create one. If called with a transaction, it will se, otherwise it will rn withot one. Always creates a new transaction. The callers transaction is sspended ntil this one completes. If called with a transaction, it will se, otherwise it throws an exception. If called with a transaction, it will throw an exception. In Container-managed transactions, there is no way to call any type of commit. The ser can initiate a rollback by calling the setrollbackonly() method on the EJB context. This call is only appropriate in certain sitations, however. If the application is deployed as a Bean-managed EJB, or a Container-managed EJB withot Transaction spport, a call to setrollbackonly() will reslt in a java.lang.illegalstateexception. Composer Enterprise Server User s Gide

71 Container-managed transactions are a very powerfl mechanism to perform complex transaction management in a heterogeneos environment. Sch a complex distribted environment reqires spport from the back end resorce manager, the middleware drivers, and the application server. 127(At this time, the Extend Application Server spports distribted transaction management across connections from a single connection pool. EJB Deployment Considerations EJB deployment is recommended in sitations where complex transactional behavior is reqired. By defalt, the Deployment Wizard bases the deploymentmode choice on the crrent Transaction Emlation Mode (as set in Tools > Configration, sing the Advanced tab). If the emlation mode yo ve chosen indicates a bean-managed EJB deployment, the Deployment Wizard will create this type of deployment. Otherwise, it will defalt to a Container-managed, Transaction Not Spported deployment. (One can easily change from Transaction Not Spported to Mandatory, Spports, Reqires New, or any of the other valid choices for bean or Container-managed transactions sing the pll-down men in the Transaction Attribte field of the EJB-Based Service Triggers Panel of the Deployment Wizard. See Chapter 4.) JDBC Transaction Control: Allowing User Transactions Manal control of transactions is sometimes reqired. For example, if there is a reqirement for two JDBC components to be in one service, the lack of distribted transaction capability across JDBC objects precldes the deployment of sch a service in a Container-managed, Transaction Reqired mode. For sch For sch sitations, extend Composer has a special checkbox on the JDBC connection component that allows ser-controlled SQL transactions. 127(This is an advanced option, and shold only be sed if yo are comfortable with the details of SQL programming. Transaction Management

72 Checking the Allow SQL Transactions box does the following: It trns the ato-commit off for the JDBC driver It translates all SQL commit and rollback commands to the eqivalent JDBC connection calls It cases extend Composer Enterprise Server to perform a rollback on the JDBC connection if the last Execte SQL Action in the JDBC component was not a commit or a rollback. This behavior is reqired when we se connection pools. When we retrn the connection to the pool, the pool manager expects to be retrned a clean connection. If we retrn a dirty connection with ncommitted changes on it, ndesirable reslts sch as table locking and transaction scope mismatches will occr. to remedy the sitation, extend detects a dirty connection, and cleans it by issing the rollback. It is somewhat safer to rollback than commit; if any exception is encontered and the component does not execte completely, the rollback will restore the database to its pre-execte state. With this behavior, it is important to explicitly isse a commit at the end of the JDBC component action model. It restores the state of the ato commit flag at the end of the transaction immediately before retrning the connection back to the pool If yo check the Allow SQL Transactions box, we recommend that yo deploy yor Composer services either as a Servlet or as an EJB in the Container-managed, Not Spported transaction mode. In addition, we strongly recommend that yo isse a commit or a rollback as the last SQL statement in yor JDBC component. It is also recommended to wrap the entire JDBC component actions in a Try/On Error block to catch any exceptions. Composer Enterprise Server User s Gide