Developer’s Guide Enterprise Server 6
Borland Software Corporation 100 Enterprise Way Scotts Valley, California 95066-3249 www.borland.com Borland Software Corporation may have patents and/or pending patent applications covering subject matter in this document. Please refer to the product CD or the About dialog box for the list of applicable patents.The furnishing of this document does not give you any license to these patents. COPYRIGHT © 1992-2004 Borland Software Corporation. All rights reserved.
Contents Chapter 1 Introduction to Borland Enterprise Server JDBC . . . . . . . Java Mail. . . . . . JTA. . . . . . . . . JAXP . . . . . . . . JNDI . . . . . . . . RMI-IIOP. . . . . . Other Technologies OptimizeIt Profiler . 1 BES Product overview. . . . . . . . . . . . . . . 1 Web Edition . . . . . . . . . . . . . . . . . . 2 Web Edition features . . . . . . . . . . . . 2 VisiBroker Edition . . . . . . . . . . . . . . . 3 VisiBroker Edition features . . . . . . . . .
Chapter 6 Connecting an Apache web server to a Borland web container. . . . . . . . . . . . . . . . 38 Connecting Borland web containers to Java Session Service . . . . . . . . . . . . . . 38 Java Session Service (JSS) configuration Chapter 5 Web server to web container connectivity 63 Session management with JSS. . . . . . . . . 63 Managing and configuring the JSS . . . . . . . 66 Configuring the JSS Partition service . . . . 67 41 Chapter 7 Apache to Borland web container connectivity .
Java:RPC provider . . . . . . . . . . . . 89 Java:EJB provider. . . . . . . . . . . . . 89 Java:VISIBROKER provider . . . . . . . 90 Java:MDB provider . . . . . . . . . . . . 92 How Borland Web Services work . . . . . . . . 92 Web Service Deployment Descriptors. . . . . . 93 Creating a server-config.wsdd file . . . . . . 94 Viewing and Editing WSDD Properties . . . 94 Packaging Web Service Application Archives . . 94 Borland Web Services examples . . . . . . . . 95 Using the Web Service provider examples. .
Constructing finder methods . . . . . . 137 Constructing the where clause . . . . . 138 Parameter substitution . . . . . . . . . 138 Compound parameters . . . . . . . . . 139 Entity beans as parameters . . . . . . . 139 Specifying relationships between entities 140 Container-managed field names . . . . 142 Setting Properties . . . . . . . . . . . . . . . 142 Using the Deployment Descriptor Editor . . 142 J2EE 1.2 Entity Bean using BMP or CMP 1.1 143 Container-managed data access support .
Chapter 21 Key cache size . . . . . . . . . . . . . 194 Connecting to Resources with BES: using the Definitions Archive (DAR) 221 Chapter 19 Transaction management 195 Understanding transactions . . . . . . . . . . 195 Characteristics of transactions . . . . . . . 195 Transaction support . . . . . . . . . . . . 196 Transaction manager services . . . . . . . . 197 Distributed transactions and two-phase commit 197 When to use two-phase commit transactions198 EJBs and 2PC transactions . . . . . . . .
Chapter 24 JMS provider pluggability Security Management . . . . . . . . . . . Component-Managed Sign-on . . . . . Container-Managed Sign-on . . . . . . EIS-Managed Sign-on . . . . . . . . . Authentication Mechanisms . . . . . . Security Map . . . . . . . . . . . . . . Security Policy Processing . . . . . . . Common Client Interface (CCI) . . . . . . . . Packaging and Deployment . . . . . . . . . . VisiConnect Features . . . . . . . . . . . . . VisiConnect Container . . . . . . . . . . .
Configuring the Transaction Level Type . 300 Configuring ra-borland.xml . . . . . . . . . 300 Anatomy of ra-borland.xml . . . . . . . 301 Configuring the element . . 302 Configuring the Security Map . . . . . . 303 Developing the Resource Adapter. . . . . . . 303 Connection Management . . . . . . . . . 303 Transaction Management . . . . . . . . . 304 Security Management . . . . . . . . . . . 304 Packaging and Deployment . . . . . . . . 305 Deploying the Resource Adapter . . . . . . .
element . . . . . . . . . . . 382 Chapter 31 EJB, JSS, and JTS Properties 385 EJB Container-level Properties . . . . . . . . 385 EJB Customization Properties: Deployment Descriptor level . . . . . . . . . . . . . . . 390 Complete Index of EJB Properties . . . . . . 392 Properties common for any kind of EJB . . 392 Entity Bean Properties (applicable to all types of entities - BMP, CMP 1.1 and CMP 2) . . . 392 Message Driven Bean Properties . . . . . 395 Stateful Session Bean Properties . . . .
Tables 3.1 3.2 4.1 4.2 4.3 4.4 5.1 5.2 5.3 5.4 5.5 5.6 5.7 8.1 8.2 12.1 27.1 29.1 Partition command options . . . . . . . 20 Partition command available arguments 21 Apache-specific directories . . . . . . . 29 Borland-specific new elements . . . . . 32 Borland additional attributes on existing elements. . . . . . . . . . . . . . . . . 34 IIS/IIOP redirector directories . . . . . . 37 IIOP connector attributes . . . . . . . . 42 IIOP directives for Apache. . . . . . . .
Figures 3.1 4.1 4.2 6.1 6.2 8.1 9.1 9.2 12.1 26.1 26.2 Partition Footprint . . . . . . . . . . . . 19 Client program binding to an object reference . . . . . . . . . . . . . . . . 38 Connecting multiple web containers to a single JSS . . . . . . . . . . . . . . . . 39 JSS Management with a Centralized JSS and Two Web Containers . . . . . . . . 64 JSS Management with Two Web Containers and a Centralized Backend Datastore. . 66 Connecting from Apache to a CORBA server . . . . . . . . . . . . . . . . . .
Chapter 1 Introduction to Borland Enterprise Server Chapter 1 The Borland Enterprise Server is a set of services and tools that enable you to build, deploy, and manage enterprise applications in your corporate environment. These applications provide dynamic content by using JSP, servlets, and Enterprise Java Bean (EJB) technologies.
B E S P r od u c t o v e r v ie w ■ Team Edition: Provides a full J2EE 1.3 implementation and can service up to 25 concurrent users on a single box. The aim of the Team Edition is to support scalability within an architecture that delivers performance and reliability at an affordable price. In short, the Team Edition is the optimal solution for small to medium deployment scales that require full J2EE capabilities.
B E S P ro d u ct ov e r v ie w ■ Web Services support, including Apache SOAP server integration, Borland XML toolkit, and development tools like the Deployment Descriptor Editor. ■ industry-proven load balancing and fault tolerance. ■ automatic session management. ■ web-enabled CORBA servers. ■ a homogeneous integration to an all-Java database with support for multiple connections.
B o r la n d E n t er p r is e S e r v e r ( B E S ) D oc u m e n t a t io n Team Edition features ■ provides a full Web Container. ■ provides a full EJB Container. ■ includes the Borland JMS services, the bundled database, JDataStore ■ Fully J2EE 1.3 compliant. ■ services up to 25 concurrent users on a single box. ■ services 1 running Partition at a time.
B o r la n d E n t e rp r is e S er v e r ( B E S ) D oc u m e n t a t io n Important ■ BES Developer's Guide - provides detailed information about packaging, deployment, and management of distributed object-based applications in their operational environment. ■ Borland Management Console User's Guide - provides information about using the Borland Management Console GUI. ■ BES VisiBroker for Java Developer's Guide - describes how to develop VisiBroker applications in Java.
D o c um en t a t i on c o n v en t i on s help Accessing online Help Topics from within BES To access the online Help Topics when running the Management Console, use one of the following methods: ■ From within the Borland Management Console, choose | Help ■ From within the DDEditor, choose | Help ■ From within the VisiBroker Console, choose | Help Documentation conventions The documentation for the Borland Enterprise Server uses the typefaces and symbols described below to indicate special text: Co
Co n t a c t in g B o rl a nd s u pp o r t Contacting Borland support Borland offers a variety of support options. These include free services on the Internet where you can search our extensive information base and connect with other users of Borland products. In addition, you can choose from several categories of telephone support, ranging from support on installation of Borland products to fee-based, consultant-level support and detailed assistance.
C o nt ac t in g B or l an d s u p po r t World Wide Web Check http://www.borland.com regularly. The Borland Enterprise Server Product Team posts white papers, competitive analyses, answers to FAQs, sample applications, updated software, updated documentation, and information about new and existing products. You may want to check these URLs in particular: ■ http://www.borland.com/products/downloads (updated software and other files) ■ http://www.borland.
Chapter 2 Borland Enterprise Server overview and architecture Chapter 2 This section contains an overview of the Borland Enterprise Server products, Editions, and architecture. Important For documentation updates, go to www.borland.com/techpubs/bes. BES architecture overview The Borland Enterprise Server is a CORBA-based, J2EE server that utilizes distributed objects throughout its architecture.
B E S s er v i c es ov e r v ie w In the following architectural diagram, your enterprise applications sit on top of the Borland Enterprise Server. An application server installation contains BES core services and Partitions. BES services overview BES services are those services available to all applications being hosted on the Borland Enterprise Server.
B E S s e r v ic e s ov e r v ie w the HTTP. protocol. The Apache web server is highly configurable and extensible through the addition of third-party modules. Apache supports clients with varying degrees of sophistication and supports content negotiation to this end. Apache also provides unlimited URL ailing. Borland has added an IIOP Plug-in to the Apache web server.
T he P a r t i t io n a nd i t s s e r v ic e s 2PC Transaction Service The Two-Phase Commit (2PC) Transaction Service exists provides a complete recoverable solution for distributed transactional CORBA applications.
T h e P a r t i t io n a n d it s s e r v ic e s Connector Service The Connector Service, also known as VisiConnect, is the Borland implementation of the Connectors 1.0 standard, which provides a simplified environment for integrating various EISs with the Borland Enterprise Server.
B o r la n d E n t er p r is e S e r v e r an d J 2 E E A P I s Session Storage Service The Java Session Service (JSS) is a service that stores information pertaining to a specific user session. The JSS provides a mechanism to easily store session information into a database. For example, in a shopping cart scenario, information about your session (your login name, the number of items in the shopping cart, and such) is polled and stored by the JSS.
B o r la n d E n t e r p ri s e S er v e r an d J 2E E A P I s ■ JNDI: the Java Naming and Directory interface ■ RMI-IIOP: remote method invocation (RMI) carried out via internet interORB protocol (IIOP) ■ JDBC: for getting connections to and modeling data from databases ■ EJB 2.0: the Enterprise JavaBeans 2.0 APIs ■ Servlets 1.
B o r la n d E n t er p r is e S e r v e r an d J 2 E E A P I s JAXP The Java APIs for XML Parsing (JAXP) enable the processing of XML documents using the DOM, SAX, and XSLT parsing implementations. Developers can easily use the parser provided with the reference implementation of the API to XML-enable their Java applications.
Chapter 3 Partitions Chapter 3 This section explains what Partitions are and how they work. It explores the Partition's footprint, facilities, configuration, and how to run a Partition. Important For documentation updates, go to www.borland.com/techpubs/bes. Partitions Overview Partitions are the runtime hosting environment for J2EE and web service application components. A Partition is a process that can be tuned to suit the application it is hosting.
C r e at in g P ar t i t i on s Additional applications and application components are also provided that can be used in your applications: ■ UDDI Server ■ Apache Struts ■ Apache Cocoon ■ Petstore J2EE blueprint application ■ SmarTicket J2EE blueprint application By enabling and disabling the various Partition containers and services, and configuring the Partition's environment, you can "right-size" the Partition to its specific task.
R u nn in g P a r t i t io n s Figure 3.1 Partition Footprint Running Partitions Partitions are typically run under the control of a management agent within a configuration, but they can also be run directly from the command line as unmanaged Partitions. In both cases the Partition requires that a Smart Agent (osagent) be running in the same sub-net on the same Smart Agent port.
R u nn i ng P a r t i t io n s Note Options that are typically static, and pertinent to both managed and unmanaged Partitions, are best encapsulated in the Partition's configuration files. Table 3.1 Partition command options Option Description -Dlog4j.configuration Path to the Partition's log4j configuration file. Default is /adm/properties/ logConfiguration.xml -Dlog4j.configuration.update.
R u nn in g P a r t i t io n s Table 3.1 Partition command options Option Description -Dpartition.management_domain.port Sets the Management ORB Smart Agent port. Default 42424. Typically used by a parent controlling process, such as the SCU. -DTomcatLoaderDebug Sets the Web Container debug level. Default 0 (zero). Table 3.2 Partition command available arguments Arguments Description -path Partition footprint path.
C o nf ig u ri n g P ar t i t io n s Any output sent to System.out or System.err is redirected as log4j events to the logs. System.out is logged at the INFO level and System.err is logged at the ERROR level. If your application uses log4j then to configure application logging you should edit the Partition's /adm/properties/logConfiguration.xml file. Configuring Partitions Partitions offer a variety of fully-configurable services.
C on f i gu r in g P a r t i t io n s Partition handling of services The element has four attributes, which are: autostart The services to be started with the Partition. startorder The startup order imposed on the Partition services included in the autostart. shutdownorder The shutdown order imposed on the Partition services running at shutdown. administer The Partition services that will appear in the Management Console as configurable.
C o nf ig u ri n g P ar t i t io n s Security management and policies Each Partition can have its own security settings. You can specify the security manager to use for each Partition by specifying a valid security class. You can also set the Policy to use for that manager (generally using a .policy file). You can configure security using either the Management Console or by setting the attributes of the node of partition.xml. For more information, see Chapter 30, “Partition XML reference”.
C on f i gu r in g P a r t i t io n s ■ At Partition initialization after any services are started but prior to the loading of any modules. ■ At Partition startup after all Partition services have loaded their respective modules. ■ At Partition shutdown before Partition services have unloaded their respective modules but prior to the services themselves shutting down. ■ At Partition termination after Partition services have been shut down.
26 B E S D e v e lo pe r ’s G u id e
Chapter 4 Web components Chapter 4 This section provides information about the web components which are included in all Borland Enterprise Server product offerings with the exception of the VisiBroker Standalone installation option. Important For documentation updates, go to www.borland.com/techpubs/bes. Apache web server implementation BES includes an implementation of the open-source Apache web server version 2.
A p a c he w e b s er v e r i m pl e m en t a t i on Otherwise, for the location of the httpd.conf file, go to the configuration.
B o r la n d w e b c on t a in e r im p le m e n t a t io n can be placed in .htaccess files, check the Context of the directive. You can control which directives can be placed in .htaccess files by configuring the AllowOverride directive in the main configuration files.
B o r la n d w eb c o n t ai n er i m p le m e nt at io n and search for the Partition managed object, partition-process sub-element directory attribute:
B o r la n d w e b c on t a in e r im p le m e n t a t io n Web application archive (WAR) file In order for the Borland web container to deploy a web application, the web application must be packaged into a Web ARchive (WAR) file. This is achieved by using the standard Java Archive tool jar command. The WAR file includes the WEB-INF directory. This directory contains files that relate to the web application.
B o r la n d w eb c o n t ai n er i m p le m e nt at io n Note All attributes listed for each element are required. Table 4.2 Borland-specific new elements Element Require d Description Default Behavior DDEditor Pane context-root no Specifies a userdefined name for the web application. To designate the application as the root web application, type "!ROOT!". By default, the WAR name (without the .war extension) is used for the application if there is no context-root at the EAR level.
B o r la n d w e b c on t a in e r im p le m e n t a t io n Table 4.2 Borland-specific new elements Element Require d Description Default Behavior DDEditor Pane authorizationdomain no Specifies which authorization domain is used for the web application. Because multiple authorization domains can be defined in an application server, you must specify the one for the web application. The authorization domain specified must be one of the domains previously defined.
B o r la n d w eb c o n t ai n er i m p le m e nt at io n Table 4.3 Borland additional attributes on existing elements Element Additional Attribute Description DDEditor Pane resource-ref (res-ref-name, jndi-name) Specifies a JNDI name to associate with the resource reference. At runtime, when a servlet looks up the specified resource reference name, the web application looks up the JNDI name in the JNDI. Note: The res-ref-name that the additional jndiname element modifies is required.
B o r la n d w e b c on t a in e r im p le m e n t a t io n Table 4.3 Borland additional attributes on existing elements Element Additional Attribute Description DDEditor Pane ejb-ref (ejb-ref-name, jndi-name) Specifies a JNDI name to associate with the EJB reference name. At runtime, when a servlet looks up the specified EJB reference name, the web application looks up the JNDI name in the JNDI. Note: The ejb-ref-name that the additional jndi-name element modifies is required.
M i c r os o f t I n t e rn e t I n f o r m a t i o n S e r v i c e s ( I I S ) w e b s er v e r host (#PCDATA)> authorization-domain (#PCDATA)> security-role (role-name, deployment-role?)> role-name (#PCDATA)> deployment-role (#PCDATA)> Adding ENV variables for the web container You add web container ENV variables for a Partition the same way you set any ENV variables for any Partition service; you use the element a
S m ar t A g e n t im p le m e n t a t io n container to the IIS web server, and from the IIS web server to a CORBA server. The IIOP redirector is supported for the following IIS versions: ■ Microsoft Windows 2000/IIS version 5.0 ■ Microsoft Windows XP/IIS version 5.1 ■ Microsoft Windows 2003/IIS version 6.0 For more information, go to Chapter 5, “Web server to web container connectivity”.
S m ar t A ge n t i m pl e m e nt a t i o n ■ “Connecting an Apache web server to a Borland web container” on page 38. ■ “Connecting Borland web containers to Java Session Service” on page 38. Connecting an Apache web server to a Borland web container As a distributed directory service, the Smart Agent registers an active ID of an object reference for the client programs to use. The following diagram shows the interaction between the client program binding to an object through the Smart Agent.
S m ar t A g e n t im p le m e n t a t io n Figure 4.
40 B E S D e v e lo pe r ’s G u id e
Chapter 5 Web server to web container connectivity Chapter 5 This section describes the web server to web container IIOP connectivity provided in the BES products. For information about Apache to CORBA connectivity, go to Chapter 8, “Apache web server to CORBA server connectivity”. Important For documentation updates, go to www.borland.com/techpubs/bes. Apache to Borland web container connectivity All BES product offerings include an implementation of the open-sourced Apache web server version 2.
A p a c he t o B or l an d w eb c o n t a in e r c on n ec t iv i t y Within the server.xml file are the following lines of code that pertain to the IIOP connector configuration. Use these lines of code and the following attributes to configure the Borland web container IIOP connector.
A p a ch e t o B or l an d we b c on t a i ne r c on n ec t iv i t y Table 5.1 IIOP connector attributes Attribute Default Description port 0 (zero) The IIOP connector port. If set to 0 (zero) - the default, a random port gets picked. If the corbaloc mechanism must be used to locate this connector from Apache or IIS, then port must be set to a value other than 0 (zero). canBufferHttp10Data true When the HTTP protocol is less than 1.
A p a c he t o B or l an d w eb c o n t a in e r c on n ec t iv i t y Use these lines of code to configure the Apache web server IIOP connector. Table 5.2 IIOP directives for Apache Directive default Description LoadModule /lib/ apache2/mod_iiop2.dll Enables Apache 2.0 to load the IIOP connector. This directive instructs the Apache web server to load the Apache mod_iiop2 module from the location specified.
A p a ch e t o B or l an d we b c on t a i ne r c on n ec t iv i t y apache2/logs/mod_iiop.log IIopLogLevel error IIopClusterConfig C:/BES/var/domains/base/configurations/j2ee/ mos/apache2/conf/WebClusters.properties IIopMapFile C:/BES/var/domains/base/configurations/j2ee/mos/ apache2/conf/UriMapFile.properties Solaris example LoadModule iiop2_module /opt/BES/lib/apache2/mod_iiop2.so IIopLogFile /opt/BES/var/domains/base/configurations/j2ee/mos/ apache2/logs/mod_iiop.
A p a c he t o B or l an d w eb c o n t a in e r c on n ec t iv i t y Additional Apache IIOP directives The following optional additional directives are available for you to use to further customize your Apache IIOP configuration. Table 5.3 Additional Apache IIOP directives Directive default Description IIopChunkedUploading (commented out) false Controls whether Apache attempts "chunked" uploads to the Borland web container IIOP connector.
A p a ch e t o B or l an d we b c on t a i ne r c on n ec t iv i t y Apache IIOP connector configuration The Apache IIOP connector has a set of configuration files that you must update with web server cluster information. By default, these IIOP connector configuration files are located in: /var/domains//configurations/ /mos/apache2/conf The two configuration files are: Table 5.
A p a c he t o B or l an d w eb c o n t a in e r c on n ec t iv i t y Note Failover and smart session are always enabled, for more information go to Chapter 7, “Clustering web components”. Cluster definition attributes Table 5.5 Attribute Required Definition webcontainer_id yes the object "bind" name or corbaloc string identifying the web container implementing the cluster.
La r g e d a t a t r an s f e r go to the Management Console User's Guide, Using the Deployment Descriptor Editor, Web Deploy Paths section. For new applications that you have deployed to the Borland web container, you need to do the following to make them available through the Apache web server. Use the UriMapFile.properties file to map HTTP URI strings to web cluster names configured in the WebClusters.properties file (see “Adding new clusters” on page 47). ■ In the UriMapFile.
L a r ge d a t a t r an s f e r Typically, the content length is known in advance for static content, but is not known for dynamic content. Downloading large data The following modes are available for downloading large data from the Borland web container to the browser: ■ Chunked download ■ Non-chunked download Implementing chunked download In the chunked download mode, the Borland web container does not wait until it has all the data to send.
La r g e d a t a t r an s f e r ■ chunked download with known content length ■ chunked download with unknown content length Chunked download with known content length In this case, a servlet or JSP knows the content length of the data in advance of the transfer. The servlet sets the Content-Length HTTP header before writing out the data. The Borland web container writes out a single response header followed by multiple chunks of data.
L a r ge d a t a t r an s f e r If you do not want the Borland web container to perform this buffering behavior, you can set the IIOP connector attribute canBufferHttp10Data="false". By default, this attribute is set to true. Note When the canBufferHttp10Data attribute is set to false, the following error message is sent to the browser: Servlet did not set the Content-Length Implementing non-chunked download This is the default transfer of data mode for the IIOP connector.
La r g e d a t a t r an s f e r Enabling chunked upload To enable chunked upload mode, you must update both of the following: ■ the Borland web container server.xml file, which is stored in your Partition's data directory: adm/tomcat/conf For more information, go to the Chapter 4, “Web components”. ■ the Apache httpd.
L a r ge d a t a t r an s f e r Chunked upload with known content length In this case, the client knows the content length of the data in advance of the transfer. The client sets the Content-Length HTTP header before writing out the data. The client writes out a single response header followed by multiple chunks of data. Apache receives this from the browser and sends data in the same fashion to the Borland web container.
I I S t o B or l an d we b c on t a i ne r c on n ec t iv i t y IIS to Borland web container connectivity All BES product offerings (with the exception of the VisiBroker Standalone installation option) include the Tomcat-based Borland web container and its IIOP connector. Also included is the IIS/IIOP redirector which provides connectivity from the Microsoft Internet Information Services (IIS) web server (not included with BES products) to the Borland web container.
I I S t o B o r la n d we b c o nt ai ne r c o n ne c t i v it y g In the Filter Properties dialog, type a Filter Name and the path for the Executable in the corresponding entry boxes. By convention, the name of the filter should reflect its task, for example: iisredir2 Also, the executable should point to the iisredir2.dll in the \bin. For example: C:\BDP\bin\iisredir2.dll h Click OK. Your new ISAPI filter appears on the list. You do not need to change the filter Priority. i Click OK.
I I S t o B or l an d we b c on t a i ne r c on n ec t iv i t y 5 Make sure the iisredir2 filter is active. a In the Computer Management dialog, right-click the Default Web Site node and choose Properties. b In the Default Web Site Properties dialog, go to the ISAPI Filters tab. c The iisredir2 filter should be marked with a green up-pointing arrow indicating that it has been activated. If not, then check the iisredir2.log file for details of why it may not have loaded correctly.
I I S t o B o r la n d we b c o nt ai ne r c o n ne c t i v it y iisredir2 Also, the executable should point to the iisredir2.dll in the \bin. For example: C:\BDP\bin\iisredir2.dll h Click OK. Your new ISAPI filter appears on the list. You do not need to change the filter Priority. i Click OK. 3 Add a "borland" virtual directory to your IIS web site. a In the Computer Management dialog, right-click Default Web Site and choose New | Virtual Directory.
I I S t o B or l an d we b c on t a i ne r c on n ec t iv i t y b In the Default Web Site Properties dialog, go to the ISAPI Filters tab. c The iisredir2 filter should be marked with a green up-pointing arrow indicating that it has been activated. If not, then check the iisredir2.log file for details of why it may not have loaded correctly. This file can be found in: \etc\iisredir2\logs. d To exit, click OK. 6 Attempt to access the \examples context via the IIS web-server.
I I S t o B o r la n d we b c o nt ai ne r c o n ne c t i v it y ■ the web container identification. ■ whether to provide automatic load balancing (enable_loadbalancing) for a particular cluster. To add a new cluster, in the WebClusters.properties file: 1 add the name of the configured cluster to the ClusterList.
I I S t o B or l an d we b c on t a i ne r c on n ec t iv i t y 3 The third uses the osagent naming scheme, but has the load balancing features disabled. Note To disable use of a particular cluster, simply remove the cluster name from the ClusterList list. However, we recommend you do not remove clusters with active http sessions attached to the web server (attached users), because requests to these "live" sessions will fail. Note Modifications you make to the WebClusters.
I I S t o B o r la n d we b c o nt ai ne r c o n ne c t i v it y Note Modifications you make to the UriMapFile.properties file automatically take effect on the next request. You do not need to restart your server(s). If the WebCluster.properties or UriMapFile.properties is altered, then it is automatically loaded by the IIOP redirector.
Chapter 6 Java Session Service (JSS) configuration Chapter 6 The Java Session Service (JSS) is a service that stores information pertaining to a specific user session. JSS is used to store session information for recovery in case of container failure. Borland provides an Interface Definition Language (IDL) interface for the use of JSS. Two implementations are bundled, one using DataExpress and another with any JDBC capable database.
S e s s i on m a n ag e m e nt w it h J S S In the diagram, “JSS Management with a Centralized JSS and Two Web Containers” on page 64, there are four virtual machines: ■ The first machine hosts the Apache web server, ■ two other machines contain an instance of the Borland web container, ■ and the fourth machine hosts the JSS and relational database (JDataStore or a JDBC datasource).
S e s s i on m a n ag e m e nt w i t h J S S ■ The first machine hosts the Apache web server, ■ the two other machines contain an instance of the Borland web container as well as each hosting the JSS, ■ and the fourth machine hosts the relational database (JDataStore or a JDBC datasource).
M a n a gi ng a n d c on f i gu r i ng t h e J S S Figure 6.2 JSS Management with Two Web Containers and a Centralized Backend Datastore Managing and configuring the JSS The JSS configuration is defined through its properties. BES supports two types of configurations; the default is to use a JDatastore, but BES supports any JDBC datasource. ■ If JSS is configured to use a JDataStore file, the database tables are automatically created by JSS.
M an a g in g a nd c on f i gu r in g t he J S S CREATE TABLE "JSS_EJB" ("KEY" STRING PRIMARY KEY, "VALUE" BINARY, "EXPIRATION" BIGINT); The JSS can run as part of the Partition side-by-side with other Partition services. Configuring the JSS Partition service As a "Partition service", JSS configuration information is located in each Partition's data directory in the partition.xml file.
68 B E S D e v e lo pe r ’s G u id e
Chapter 7 Clustering web components Chapter 7 This section discusses the clustering of multiple web components which includes Apache web servers and the Tomcat-based Borland web containers. In a typical deployment scenario, you can use multiple Borland Partitions to work together in providing a scalable n-tier solution. Each Borland Partition can have the same or different services. Depending on your clustering scheme, these services can be turned off or on.
T he B o r la n d I I O P c o nn e c t o r The Borland IIOP connector The IIOP connector is software that is designed to allow an http web server to redirect requests to the Borland web container. The Borland Enterprise Server includes the IIOP connector for the Apache 2.0 and Microsoft Internet Information Server(IIS) versions 5.0, 5.1 and 6.0 web servers. The job of handling the redirection of http requests is split between two components: ■ a native library running on the web server.
T he B o r la n d I I O P c o n ne c t o r locations where the web containers are running using the CORBA corbaloc semantics. For example: corbaloc::172.20.20.28:30303,:172.20.20.29:30304/tc_inst1 In the above corbaloc example string: ■ two TCP/IP endpoints are configured for a web container named "tc_inst1" ■ a web container with an object name of "tc_inst1" is running on host 172.20.20.
Smart session handling When there is no session involved, the IIOP connector can do indiscriminate round robining. However, when sessions are involved, it is important that Apache routes its session requests to the web container that initiated the session. In other http-to-servlet redirectors (and in the earlier version of the IIOP connector) this is achieved by maintaining a list of sessions-ids-to-webcontainer-id's in the web server's cache.
S e t t i ng u p y ou r w eb c o n t ai n er w i t h J S S Modifying a Borland web container for failover In the Borland web container configuration file, server.xml, you need to add an entry similar to the following code sample for each web application. For more information about the server.xml file, go to Chapter 5, “Web server to web container connectivity”. PAGE 86U s in g H T T P s e s s io ns Object myState = session.getAttribute("myState"); // Modify mystate here and do not call setAttribute () Your configuration file, server.xml, will have the following code snippet: where xxx is the time interval in seconds that you want the session data to be stored.
U s in g HT T P s e s s io n s ■ URL rewriting: The URL that the user clicks on is dynamically rewritten to have session information.
76 B E S D e v e lo pe r ’s G u id e
Chapter 8 Apache web server to CORBA server connectivity Chapter 8 The Apache IIOP connector can be configured to enable your web server to communicate with any standalone CORBA server implementing the ReqProcessor Interface Definition Language (IDL). This means you can easily put a web-based front-end on almost any CORBA server.
W e b- e n ab li n g yo u r C O R B A s e r v e r Determining the urls for your CORBA methods In order to make your CORBA server accessible over the internet, you need to: 1 Decide what business operations you want to expose. 2 Provide a url for those business operations (CORBA methods). For example, your banking company's CORBA server is implementing the methods: debit(), credit(), and balance() and you want to expose these business methods to users through the internet.
W eb - e na b li ng y o u r C O RB A s er v e r string name; string value; }; typedef sequence NVList; typedef sequence OctetSequence_t; struct HttpRequest { string authType; // auth type (BASIC,FORM etc) string userid; // username associated with request string appName; // application name (context path) string httpMethod; // PUT, GET etc, string httpProtocol; // protocol HTTP/1.0, HTTP/ 1.
C o nf ig u ri n g y o u r A p ac h e w e b s e r v e r t o in v o k e a CO R B A s e r v er method is a request from a browser: HttpRequest, and the output for the process() method is an html page contained in: HttpResponse. Configuring your Apache web server to invoke a CORBA server Before an Apache web server can invoke a CORBA server, you must modify the lines of code that pertain to the IIOP connector in the httpd.conf file.
Co n f ig u r in g y o ur A p ac h e w e b s e rv e r t o in v o k e a C O R B A s er v e r The two configuration files are: Table 8.1 Apache IIOP connection configuration files IIOP configuration file Description WebClusters.properties Specifies the cluster(s) and the corresponding CORBA server(s) for each cluster. UriMapFile.properties Maps URI references to the clusters defined in the WebClusters.properties file.
C o nf ig u ri n g y o u r A p ac h e w e b s e r v e r t o in v o k e a CO R B A s e r v er Note Failover and smart session are always enabled, for more information go to Chapter 7, “Clustering web components”.. Cluster definition attributes Table 8.2 Attribute Required Definition webcontainer_id yes the object "bind" name or corbaloc string identifying the web container implementing the cluster.
Co n f ig u r in g y o ur A p ac h e w e b s e rv e r t o in v o k e a C O R B A s er v e r server. Use the UriMapFile.properties file to map http uri strings to web cluster names (CORBA instances) configured in the WebClusters.properties file. ■ In the UriMapFile.properties file, type: = where is a standard URI string or a wild-card string, and is the cluster name as it appears in the ClusterList entry in the WebClusters.properties file.
84 B E S D e v e lo pe r ’s G u id e
Chapter 9 Borland Enterprise Server Web Services Chapter 9 The Borland Enterprise Server provides an out-of-the-box web services capability in all Borland Partitions. Important For documentation updates, go to www.borland.com/techpubs/bes. Web Services Overview A Web Service is an application component that you can describe, publish, locate, and invoke over a network using standardized XML messaging.
W e b S er v i c es a n d P a rt it i on s 2 The Service Broker publishes the web services for the Service Requestor to access. The information published describes the web service and its location. 3 The Service Requestor interacts with the Service Broker to find the web services. The Service Requestor can then bind or invoke the web services. ■ The Service Provider hosts the web service and makes it available to clients via the Web.
W e b S er v i c es a n d P a r t i t io n s Additionally, you can expose a previously deployed stateless session bean as a web service. For more information, see the Management Console User's Guide, Export EJB as a Web Service Wizard.
W e b S er v i c e p r o v id e rs Figure 9.2 Borland Web Services Architecture Web Service providers The Borland web services engine includes a number of providers. A provider is the link that connects a client web service request to the user's class on the server side. All providers do the following: ■ Create an instance of an object on which they can invoke methods. The exact way of creating this object differs from provider to provider.
W e b S e r v ic e pr o v id e r s Specifying web service information in a deploy.wsdd file When installing a new web service, you must name the web service and specify which provider the service is going to use. Each provider takes different parameters. The following describes the service providers and the required parameters for each. Java:RPC provider This provider assumes that the class serving the web service is in the application archive (WAR).
W e b S er v i c e p r o v id e rs ■ className: The name of the EJB remote interface. ■ allowedMethods: The methods that are allowed to be invoked on this EJB, separated by spaces. The EJB can have more methods than listed here; the methods listed here are available for remote invocation. Example: PAGE 103W e b S e r v ic e pr o v id e r s The 3 possible values are: osagent The object is assumed to be in osagent. The bind() method on helper is used to locate the object. The Server object must be registered with the same osagent that the Partition is using. If poaName is also specified, objectName is located under that POA. This is the default value of the parameter. nameservice The object is assumed to be in Naming Service. The resolve() method on the root context is used to locate the object.
H o w B o rl a nd W eb S e r v ic e s w o r k PAGE 105W e b S er v i c e D e p lo y m e nt De s c r ip t o r s ■ “Java:RPC provider” on page 89 ■ “Java:EJB provider” on page 89 ■ “Java:VISIBROKER provider” on page 90 ■ “Java:MDB provider” on page 92 Web Service Deployment Descriptors Web services are deployed as part of a WAR. A single WAR can contain multiple web services. You can also deploy multiple WARs with each containing many web services.
P a c k a gi n g W e b S e rv i c e A p pl ic a t i on A r c h iv e s Creating a server-config.wsdd file To create the server-config.wsdd: ■ Use JBuilder to generate the deployment descriptor as part of your WAR. or 1 Use a text editor to write a deploy.wsdd file. Refer to the deploy.wsdd file in /examples/webservices/java/server. 2 Run the “Tools Overview” on page 96 with the deploy.wsdd file by typing: prompt>java org.apache.axis.utils.Admin server deploy.wsdd The server-config.
B o r la n d W e b S er v i c es e x a m p le s Borland Web Services examples To help you get started with developing and deploying web services, we provide samples and examples for the Borland web services engine. These examples are included in your Borland Enterprise Server installation in: /examples/webservices/ The examples that illustrate the different “Web Service providers” on page 88, are located in the web services examples directory in the Java, EJB, MDB or VisiBroker folder.
T oo l s O v e r v ie w ■ Deployment Wizard, for more information go to the Management Console User's Guide, Deployment Wizard section. 3 Run. To run an example, navigate to its directory and use the ant run- client command. For example, to run the Java Provider client: C:/BDP/examples/webservices/java>Ant run-client Apache Axis Web Service samples The Apache Axis web service samples are already deployed in the axissamples.war file present in the Borland Partition.
T o o ls O v e r v ie w Note You must set your CLASSPATH to include all jar files in the \lib\ axis directory, before you run the following command. WSDL2Java tool The WSDL2Java is an Apache Axis utility class that generates Java classes from a WSDL file. This tool can generate java stubs (used on the client side), or java skeletons (used on the server side). The generated files make it easy to develop your client or server for a given WSDL.
98 B E S D e v e lo pe r ’s G u id e
Chapter 10 Web applications bundled with BES Chapter 10 This section describes the Apache Cocoon and Apache Struts for which BES includes support. For more information about Apache, go the 3rd Party Documentation, Apache2 section. The Cocoon servlet is pre-installed in the Tomcat web container upon which the Borland web container is based. The Struts framework is also pre-installed in the Borland web container. For more information about the Borland web container, go to Chapter 4, “Web components”.
A b o u t C oc o o n An unmodified copy of the properties file is included as part of the Cocoon webapp (cocoon.war) distributed with BES. You can customize this file to create your own cocoon.properties file. This unmodified cocoon.properties file is compiled in with the Borland web container. As the default properties file, it is used whenever the file specified in the Cocoon servlet definition cannot be found. Cocoon is an open-source product distributed by the Apache Software Foundation.
Chapter 11 Writing enterprise bean clients Chapter 11 Important For documentation updates, go to www.borland.com/techpubs/bes. Client view of an enterprise bean A client of an enterprise bean is an application--a stand-alone application, an application client container, servlet, or applet--or another enterprise bean. In all cases, the client must do the following things to use an enterprise bean: ■ Locate the bean's home interface.
Initializing the client The SortClient application imports the necessary JNDI classes and the SortBean home and remote interfaces. The client uses the JNDI API to locate an enterprise bean's home interface. A client application can also use logical names (as recommended in the various J2EE specifications) to access resources such as database connections, remote enterprise beans, and environment variables.
C li e nt v i ew o f a n e n t er p r is e b ea n ... //do the sort and merge work sort.remove(); } } The main() routine of the client program throws the generic exception Exception. When coded this way, the SortClient program does not have to catch any exceptions that might occur, though if an exception occurs it will terminate the program. Obtaining the remote interface Now that we have obtained the home interface of an enterprise bean we can get a reference to the enterprise bean's remote interface.
creditCardNumber, and expirationDate--then calls the create() method. This is shown in the code sample below: Cart cart; { String cardHolderName = "Jack B. Quick"; String creditCardNumber = "1234-5678-9012-3456"; Date expirationDate = new GregorianCalendar(2001, Calendar.JULY, 1).getTime(); cart = home.create(cardHolderName, creditCardNumber, expirationDate); } Session beans do not have finder methods.
C li e nt v i ew o f a n e n t er p r is e b ea n value type in RMI-IIOP. The primary key class can be any class--a Java class or a class you've written yourself. For example, you have an Account entity bean that defines the primary key class AccountPK. AccountPK is a String type, and it holds the identifier for the Account bean.
bean methods in the same way that it invokes any method, such as its own method summarize(). ... Cart cart; { ... // obtain a reference to the bean's remote interface cart = home.create(cardHolderName, creditCardNumber, expirationDate); } // create a new book object Book knuthBook = new Book("The Art of Computer Programming", 49.95f); // add the new book item to the cart cart.addItem(knuthBook); ... // list the items currently in the cart summarize(cart); cart.removeItem(knuthBook); ...
C li e nt v i ew o f a n e n t er p r is e b ea n persistent storage). Later, you can retrieve the handle from storage and use it to reestablish a reference to the enterprise bean. However, you can only use the remote interface handle to recreate the reference to the bean; you cannot use it to recreate the bean itself.
} ... When finished with the session bean handle, the client can remove it with the javax.ejb.EJBHome.remove(Handle handle) method. Managing transactions A client program can manage its own transactions rather than letting the enterprise bean (or container) manage the transaction. A client that manages its own transaction does so in exactly the same manner as a session bean than manages its own transaction.
G e t t i n g i nf or m a t i on a bo u t a n e n t er p r is e b ea n Getting information about an enterprise bean Information about an enterprise bean is referred to as metadata. A client can obtain metadata about a bean using the enterprise bean's home interface getMetaData() method. The getMetaData() method is most often used by development environments and tool builders that need to discover information about an enterprise bean, such as for linking together beans that have already been installed.
EJB to CORBA mapping There are a number of aspects to the relationship between CORBA and Enterprise JavaBeans. Three important ones are the implementation of an EJB container/server with an ORB, the integration of legacy systems into an EJB middle tier, and the access of enterprise beans from non-Java components, specifically clients. The EJB specification is currently only concerned with the third aspect. CORBA is a very suitable and natural platform on which to implement an EJB infrastructure.
E J B t o C O RB A m ap p in g For example, look at the IDL interface for an ATM enterprise session bean that has methods to transfer funds between accounts and throws an insufficient funds exception. By applying the Java/IDL mapping to the home and the remote interface, you get the following IDL interface.
apply. The initialization of the ORB determines the context returned by resolve_initial_references(). For example, a C++ Client can locate the home interface to the ATMSession bean, which has been registered with a JNDI string name "transaction/ corbaEjb/atm". You first obtain the initial naming context. Object_ptr obj = orb->resolve_initial_refernces("NameService"); NamingContext initialNamingContext= NamingContext.
E J B t o C O RB A m ap p in g Current current = Current.narrow( obj ); if( current == NULL ) { cerr << "Couldn't resolve current" << endl; exit( 1 ); } // execute transaction try { current->begin(); atmSession->transfer("checking", "saving", 100.00 ); current->commit( 0 ); } catch( ... ) { current->rollback(); } } catch( ... ) { ... } Mapping for security Security aspects of the EJB specification focuses on controlling access to enterprise beans.
114 B E S D e ve l op e r ’s G u id e
Chapter 12 The VisiClient Container Chapter 12 VisiClient is a container that provides a J2EE environment for services for application clients. Containers are an integral part of J2EE applications. Most applications provide containers for each application type. Application clients depend on their containers to supply system services to all J2EE components. Important For documentation updates, go to www.borland.com/techpubs/bes.
A p p li c at io n Cl ie n t a r c hi t e c t u r e Figure 12.1 VisiClient architecture Packaging and deployment Deploying the application client components into a VisiClient container requires the specification of deployment descriptors using XML. (Refer to J2EE 1.3 Specification for more information about application clients, and their deployment into a J2EE 1.3 compliant container.
D o c um e n t T y p e D ef i n it i on s ( D T D s ) container or to an EAR file. The following sections in this chapter describe this process in detail. Benefits of the VisiClient Container VisiClient offers users a range of benefits from the use of J2EE applications. These include: ■ Client code portability: Applications can use logical names (as recommended in the J2EE specifications) to access resources such as database connections, remote EJBs and environment variables.
D o c um en t T y p e D e f i ni t io n s ( D T D s ) 1.3//EN""http://www.borland.com/devsupport/appserver/dtds/applicationclient_1_3-borland.
D o c um e n t T y p e D ef i n it i on s ( D T D s ) reference to a jdbc datasource mentioned down in the DD section jdbc/CheckingDataSource javax.sql.DataSource Container Example of a vendor-specific file:
S u p p or t o f re f e r e nc e s a n d lin k s userTransaction.begin(); // locate the datasource using resource-ref name Object resRef = context.lookup("java:comp/env/jdbc/ CheckingDataSource"); java.sql.Connection conn = ((javax.sql.DataSource)resRef).getConnection(); //do some database work. userTransaction.commit(); ............... Support of references and links During application assembly and deployment you must verify that all EJB and resource references have been properly linked.
S up p o rt o f re f e r e nc e s a n d l in k s that is referencing the enterprise bean. This allows multiple enterprise beans with the same ejb-name to be uniquely identified. If the path is not specified, container picks first matching EJB-name that it finds from list of EJB JARs inside EAR and throws an exception if doesn't find a bean with same name in ejb-link element.
E m be d di n g V is iC l ie n t C on t a i ne r f u n c t io n al it y in t o a n ex i s t in g a pp l ic a t io n 1 Copy the following JAR files from /lib to client machine: ■ lm.jar ■ xmlrt.jar ■ asrt.jar ■ vbjorb.jar ■ vbsec.jar ■ jsse.jar ■ jaas.jar ■ jcert.jar ■ jnet.jar ■ vbejb.jar 2 Copy the following JAR file from /jms/tibco/clients/java to client machine: ■ tibjms.jar 3 Copy /bin/appclient.config to client machine.
Us e o f M a ni f e s t f i le s descriptors. An IllegalArgumntException exception is thrown if the data provided is not recognized as a valid deployment descriptor. Sample code This example shows usage of this method: public static void main (String[] args) { . . . // load deployment descriptor files java.io.FileInputStream ddSun = new java.io.FileInputStream("META-INF/application-client.xml"); java.io.FileInputStream ddBorland = new java.io.FileInputStream("META-INF/application-client-borland.
E x c e p t io n h an d li n g example it is SortClient. The container expects to have a method with the following signature in this class: public static void main(String[ ] args) throws Exception {...} The container will report an error and exit if it doesn't find the main method. The client verify utility, which comes with VisiClient, tries to locate a main class and reports an error if it doesn't find one.
O t h er f e at u r e s ■ ejb-refs are valid (that is, a JNDI name for the target EJB is specified in the Borland-specific file). ■ If ejb-ref is an ejb-link, then the archive should be an EAR file. There must also be an EJB with the same name as the ejb-link value in the EAR file. ■ Resource references are valid.
126 B E S D e ve l op e r ’s G u id e
Chapter 13 Caching of Stateful Session Beans Chapter 13 The EJB Container supports stateful session enterprise beans using a highperformance caching architecture based on the Java Session Service (JSS). There are two pools of objects: the ready pool and the passive pool. Enterprise beans transition from the ready pool to the passive pool after a configurable timeout. Transitioning an enterprise bean to the passive pool stores the enterprise bean's state in a database.
P a s s i va t i n g S es s i on B e a n s its state is sent to persistent storage and the bean instance is removed from memory. Simple Passivation Passivation timeouts are set at the container-level. You use the property ejb.sfsd.passivation_timeout to configure the length of time a session bean can go un-accessed before its state is persisted and its instance removed from memory. This length of time is specified in seconds. The default value is five seconds. This property can be set in the partition.
S e s s io ns i n se c o n da r y s t o r ag e Again, aggressive passivation is set Partition-wide using the boolean property ejb.sfsb.aggressive_passivation. Setting the property to true (the default) stores the session's state regardless of whether it was accessed before the the last passivation attempt. Setting the property to false allows the container to use only simple passivation. Again, this property is set in the container's properties file partition.
S e s s i on s i n s e c o n da r y s t o r ag e Setting the keep alive timeout for a particular session bean You may wish to have certain session beans hosted in your container have their passivated states stored for greater or lesser periods of time than others. You can use the element in the ejb-borland.xml file to set the keep alive timeout for a particular bean.
Chapter 14 Entity Beans and CMP 1.1 in Borland Enterprise Server Chapter 14 Here we'll examine how entity beans are deployed in the Borland Enterprise Server and how persistence of entities can be managed. This is not, however, an introduction to entity beans and should not be treated as such. Rather, this document will explore the implications of using entity beans within Borland Partitions. We'll discuss descriptor information, persistence options, and other container-optimizations.
C o nt ai n er - m a n ag e d pe r s is t en c e a nd R e la t io n s h ip s jar.xml descriptor is fully-documented at the Sun Java Center. The DTD for ejb-borland.xml is reproduced in this document and its usage documented here. The Borland proprietary descriptor contains a number of properties that can be set to optimize container performance and manage the persistence of your entity beans.
I m pl e m e nt i n g a n en t i t y b ea n methods that correspond to those declared in the remote or local and home interfaces. Packaging Requirements Like session beans, entity beans can expose their methods with their interfaces. Each Entity Bean must also have corresponding entries in its JAR's deployment descriptors. The standard deployment descriptor, ejb-jar.xml contains essentially three different types of deployment information.
I m pl e m en t i ng a n e nt it y b e a n key values. A more elegant means of generating primary keys is for the user to implement a separate class that generates primary keys. This class can also implement database-specific programming logic for generating primary keys. Generating primary keys from a user class With enterprise beans, the primary key is represented by a Java class containing the unique data.
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r For the where clause, specify multiple field names in the same manner that you specify single field names. Use "and" to separate each field. The format is = :[ejb/] Note that the equal (=) sign is one of several possible notations. You could also specify greater than (>), less than (<), greater than or equal (>=), or less than or equal (<=).
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r deployer maps this persistence schema to the database and creates any other necessary classes for the beans' maintenance. Information on J2EE 1.3 entity beans and CMP 2.0 is found in the Chapter 16, “Using BES Properties for CMP 2.x”. BES CMP engine's CMP 1.
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r Providing CMP metadata to the Container According to the EJB Specification, the deployer must provide CMP metadata to the EJB container. The Borland Container captures the CMP-relevant metadata in the XML deployment descriptor. Specifically, the Borland Container uses the vendor-specific portion of the deployment descriptor for the CMP metadata.
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r container. When that flag is enabled, it prints the exact statements constructed by the Container. While other EJB Container products use code generation to support CMP, the Borland Container does not use code generation because it has serious limitations.
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r The Container composes a SQL select statement whose where clause is: balance > ? Note that the :balance parameter in the deployment descriptor becomes a question mark (?) in the equivalent SQL statement. When invoked, the Container substitutes the value of the parameter :balance for the ? in the where clause.
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r When you use an EJBObject as a compound type (using the dot notation), you are actually accessing the underlying get method for the field in the definition. For example, the following in the definition: order_id = :order.orderId calls the getOrderId() method on the order EJBObject and uses the result of the call in the selection criterion.
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r Now examine the code for both classes: //Address Class public class Address extends EntityBean { public int id; public String street1; public String street1; public String city; public String state; public String zip; public Country country; // this is a direct pointer to the Country } //Country Class public class Country extends EntityBean { public int id; public String name; public int exchange; public Strin
S e t t i n g P r op e r t ie s Container-managed field names The Borland Container has changed the container-managed persistent field names so that they are more Java friendly. SQL column names often prepend a shortened form of the table name, followed by an underscore, to each column name. For example, in the address table, there is a column for the city called addr_city. The full reference to this column is address.addr_city. With the Borland Container, this maps to the Java field Address.
S e t t in g P ro p e rt ie s User's Guide for complete information on the use of the Deployment Descriptor Editor and other related tools. J2EE 1.2 Entity Bean using BMP or CMP 1.
S e t t i n g P r op e r t ie s Descriptor Element Navigation Tree Node/ Panel Name DDEditor Tab Finder WHERE Clause Bean:CMP1.1 Finders Finder Load State option Bean:CMP1.1 Finders Container-managed data access support For container-managed persistence, the Borland EJB Container supports all data types supported by the JDBC specification, plus some other types beyond those supported by JDBC.
S e t t in g P ro p e rt ie s For example, suppose you have a CMP field called "select". You can use the following environment property to map "select" to a column called "SLCT", as shown below. select SLCT Using null values It is possible that your database values can contain SQL null values.
S e t t i n g P r op e r t ie s However, the Container can detect the dialect from the URL for the JDataStore database. Thus, for JDataStore, the Container will create these tables regardless of whether you explicitly specify the dialect.
S e t t in g P ro p e rt ie s Java type JDBC SQL type java.sql.Timestamp TIMESTAMP java.util.Date TIMESTAMP java.io.Serializable VARBINARY Automatic table mapping The Borland EJB container has the capability to automatically map Java types defined in the enterprise bean code to database table types. However, while it may create these tables automatically, it does not necessarily use the most optimal mapping approach.
S e t t i n g P r op e r t ie s Java types Oracle Sybase/MSSQL DB2 String VARCHAR(2000) TEXT VARCHAR(2000) java.math.BigDecima l NUMBER(38) DECIMAL(28,28) DECIMAL byte[] LONG RAW IMAGE BLOB java.sql.Date DATE DATETIME DATE java.sql.Time DATE DATETIME TIME java.sql.Timestamp DATE DATETIME TIMESTAMP java.util.Date DATE DATETIME TIMESTAMP java.io.
Chapter 15 Entity Beans and Table Mapping for CMP 2.0 Chapter 15 Here we'll examine how entity beans are deployed in the Borland Enterprise Server and how persistence of entities can be managed. This is not, however, an introduction to entity beans and should not be treated as such. Rather, this document will explore the implications of using entity beans within Borland Partitions. We'll discuss descriptor information, persistence options, and other container-optimizations.
C o nt ai n er - m a n ag e d pe r s is t en c e a nd R e la t io n s h ip s jar.xml descriptor is fully-documented in the J2EE 1.3 Specification. The DTD for ejb-borland.xml is reproduced in this document and aspects of its usage documented here. The Borland proprietary descriptor allows for the configuration of a number of properties that can be set to optimize container performance and manage the persistence of your entity beans.
C on t a in e r - m a na g ed p er s i s t e nc e a nd R e la t io n s h ip s You must deploy these interfaces as well as an implementation of your bean's class. Each Entity Bean must also have corresponding entries in its JAR's deployment descriptors. The standard deployment descriptor, ejb-jar.xml contains essentially three different types of deployment information.
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r You can declare an entity bean reentrant in the deployment descriptor; however, take special care in this case. The critical issue is that a Container can generally not distinguish between a (loopback) call within the same transaction and a concurrent invocation (in the same transaction context) on that same entity bean.
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r editing is also managed by the PM. This simplifies interactions with the container and allows the PM to optimize its read and write operations. This approach also suppresses duplicate find requests by tracking returned primary keys for requested entities. Data from duplicate find operations can then be returned from the first load of the entity's data. Borland CMP engine's CMP 2.0 implementation In CMP 2.
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r ■ SelectForUpdate ■ SelectForUpdateNoWAIT ■ UpdateAllFields ■ UpdateModifiedFields ■ VerifyModifiedFields ■ VerifyAllFields The behavior exhibited by the container corresponds to the value of the optimisticConcurrencyBehavior, found in the Table Properties section of Chapter 16, “Using BES Properties for CMP 2.x”.
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r ■ UpdateModifiedFields ■ VerifyModifiedFields ■ VerifyAllFields SelectForUpdate Use this option for pessimistic concurrency. With this option specified, the database locks the row until the current transaction is committed or rolled back. Other selects on the row are blocked until then. SelectForUpdateNoWAIT Use this option for pessimistic concurrency.
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r (You will need to handle these rollbacks appropriately.) Otherwise, the transaction commits. Again using the same table, the CMP engine generates the following SQL using the VerifyModifiedFields behavior if only VALUE1 was updated: UPDATE MyTable SET (VALUE1 = value1) WHERE KEY = key AND VALUE1 = oldVALUE1 VerifyAllFields This option is very similar to VerifyModifiedFields, except that all fields are verified.
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r CustomerEJB ejb.datasource serial://ds/myDatasource The Borland CMP engine will automatically create tables in this datasource based on the bean's name and fields. CASE 2: A deployment environment with (or without) existing database tables using supported databases.
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r Basic Mapping of CMP fields to columns Basic field mapping is accomplished using the element in the ejbborland.xml deployment descriptor. In this element, you specify a field name and a corresponding column to which it maps.
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r Address.AddressState STATE Address.AddressZip ZIP . . Note that we use one element per database column.
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r . . orderNumber ORDER_NO line LINE item ITEM quantity QUANTITY.
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r field> element containing the relationship. The descriptor then uses elements to specify relationships between two tables, a and a . You must observe the following cardinalities: ■ One must be defined per direction; if you have a bidirectional relationship, you must define an for each bean with each referencing the other.
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r SpecialInfo CASE 2: a bidirectional one-to-many relationship. Here, we have a Customer entity bean with a primary key, CUSTOMER_NO, that is also a foreign key in an Order entity bean. We want the Borland EJB Container to manage this relationship.
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r customers ORDER CUSTOMER_NO CUSTOMER CUSTOMER_NO . .
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r EMPLOYEE_PROJECTS EMP_NAME PROJ_ID PROJ_ID PROJ_NAME PROJECT PROJ_ID PROJ
C on t a in e r - M an a g ed P e r s is t e n c e i n B o r la n d E n t e r p ri s e S er v e r Database cascade delete support Borland Enterprise Server supports the database cascade delete feature, which allows an application to take advantage of a database's built in cascade delete functionality. This reduces the number of SQL operations sent to the database by the container, therefore improving performance.
C o nt ai n er - M a n ag e d P er s i s t e nc e i n B or l an d E n t e r pr i s e S er v e r LineItemEJB order LINE_ITEM_TABLE ORDER_NUMBER ORDER_TABLE
Chapter 16 Using BES Properties for CMP 2.x Chapter 16 Setting Properties Most properties for Enterprise JavaBeans can be set in their deployment descriptors. The Borland Deployment Descriptor Editor (DDEditor) also allows you to set properties and edit descriptor files. Use of the Deployment Descriptor Editor is described in the Borland Enterprise Server User's Guide.
S e t t i n g P r op e r t ie s performed via the EJB Designer, a component of the Deployment Descriptor Editor. The following table shows descriptor information and where in the Deployment Descriptor Editor that information can be entered. The EJB Designer CMP 2.x properties are set using the EJB Designer. The EJB Designer appears as a Tab in the Deployment Descriptor Editor. See the Management Console User’s Guide, Using the Deployment Descriptor Editor section for details on this feature. J2EE 1.
S e t t in g P ro p e rt ie s Descriptor Element Navigation Tree Node/ Panel Name DDEditor Tab EJB Local Links Bean EJB Local References Resource Environmental References for JMS Bean Resource Env Refs Container Transactions Bean:Container Transactions Container Transactions Transactional Method Bean:Container Transactions Container Transactions Transactional Method Interface Bean:Container Transactions Container Transactions Transactional Attribute Bean:Container Transactions Container
S e t t i n g P r op e r t ie s 4 Edit the properties you desire and click OK. The properties themselves are discussed below. Editing Table and Column properties Table and Column properties can only be set by editing the ejb-borland.xml descriptor file from the DDEditor's Vendor XML Tab, or by using the EJB Designer. To edit or add Table and Column properties: 1 Start the DDEditor and open the deployment descriptor for the JAR containing your entity beans.
S e t t in g P ro p e rt ie s 3 Select the XML Tab. Two additional Tabs are now available in the Properties Pane; Standard and Vendor. Choose Vendor. 4 Locate or add either the or elements and add property definitions in accordance with the borland-specific DTD, shown in Chapter 32, “ejb-borland.xml”. Germane entries are in bold. Descriptions of the entity, table, and column properties follow, including their data type, default values, and a property description.
S e t t i n g P r op e r t ie s Entity Properties These properties are for CMP 1.1 and above implementations: Property Type Default Description ejb.maxBeans InCache lava.lang.Integer 1000 This option specifies the maximum number of beans in the cache that holds on to beans associated with primary keys, but not transactions. This is relevant for Option "A" and "B" (see ejb.transactionCommitMode below). If the cache exceeds this limit, entities will be moved to the ready pool by calling ejbPassivate.
S e t t in g P ro p e rt ie s Property Type Default Description ejb.maxBeans InTransactio ns lava.lang.Integer 500* see Description A transaction can access any/large number of entities. This property sets an upper limit on the number of physical bean instances that EJB container will create. Irrespective of the number of database entities/rows accessed, the container will manage to complete the transaction with a smaller number of entity objects (dispatchers).
S e t t i n g P r op e r t ie s Property Type Default Description ejb.datasource java.lang.String N/A Default JDBC datasource to use in case no table-properties have been set. CMP 2.x only. ejb.truncateTableNa me java.lang.Boolean False If no table name is specified, CMP2.x engine will use the EJB name as the table name. EJB names can be more than 30 characters in length. Moreover, certain databases have a restriction on the table length to be 30 characters or less.
S e t t in g P ro p e rt ie s and Column Properties, which manage persistence. Refer to these properties below to see where migration issues may appear. Property Type Default Description datasource java.lang.String None JNDI datasource name of the database for this table. optimisticConcu rrencyBehavior java.lang.String UpdateM odified Fields The container uses optimistic or pessimistic concurrency to control multiple transactions (updates) that access shared tables.
S e t t i n g P r op e r t ie s Property Type Default Description primaryKeyGener ationListener java.lang.String None Specifies a class, written by the user, that implements com.borland.ejb.pm.PrimaryKeyGeneratio nListener interface and generates primary keys.. dbcAccesserFact ory java.lang.String None A factory class that can provide accessor class implementations to get values from a java.sql.ResultSet, and set values for a java.sql.PreparedStatement. getPrimaryKeyBe foreInsertSql java.lang.
S e t t in g P ro p e rt ie s Column Properties Property Type Default Description ignoreOnInsert java.lang.String false Specifies the column that must not be set during the execution of an INSERT statement. This property is used in conjunction with the getPrimaryKeyAfterInsertSql property. createColumnSql java.lang.String None Use this property to override the standard data-type lookup and specify the data type manually, use this property. Local transactions support the javax.ejb.
S e t t i n g P r op e r t ie s Security Properties These security properties are specified in the portion of the deployment descriptor. Property Type Default Description ejb.security.transportType Enumerated SECURE_ONLY This property configures the Quality of Protection of a particular EJB. If set to CLEAR_ONLY, only non-secure connections are accepted from the client to this EJB. This is the default setting, if the EJB does not have any method permissions.
Chapter 17 EJB-QL and Data Access Support Chapter 17 EJB-QL allows you to specify queries in an object oriented query language, EJB-QL. The Borland CMP engine translates these queries into SQL queries. The Borland Enterprise Server provides some extensions to the EJB-QL functionality described in the Sun Microsystems EJB 2.x Specification. Important For documentation updates, go to www.borland.com/techpubs/bes.
A g g r eg a t e F u n c t io n s in E J B -Q L l.lineItemId=?1 The return types of the EJB-QL query method are: ■ If the Java type of the cmp-field is an object type, and the query method is a single-object query method, the return type is an instance of that object type. ■ If the Java type of the cmp-field is an object type and the query method returns multiple objects, a collection of instances of the object type is returned.
A g g re g a t e F u nc t i o ns i n E J B - Q L Local SELECT MAX(l.lineItemId) FROM Account AS a, IN (a.accountLineItem) l WHERE l.accountId=?1 The following restrictions must be observed for aggregate functions: ■ Arguments to the SUM and AVG functions must be numeric (Integer, Byte, Long, Short, Double, Float, and BigDecimal).
S u p p or t f or O R DE R B Y Aggregate Function Argument data type Expected return type COUNT java.lang.Short java.lang.Long MIN, MAX, SUM java.lang.Short java.lang.Short AVG java.lang.Short java.lang.Double COUNT java.lang.Short java.lang.Long MIN, MAX, SUM java.lang.Double java.lang.Double AVG java.lang.Double java.lang.Double COUNT java.lang.Double java.lang.Long MIN, MAX, SUM java.lang.Double java.lang.Double AVG java.lang.Double java.lang.Double COUNT java.lang.
S u p po r t f o r G R O UP B Y findCustomerByNumber SELECT Distinct Object(c) from CustomerBean c WHERE c.no > 1000 ORDER BY c.LNAME You can specify either ASC (ascending) or (DESC) descending in your EJBQL as well. If you do not specify either, the results will be ordered ascending by default.
S u b - Q u e ri e s We can get the average salary of each department using a single query method: SELECT e.DEPARTMENT, AVG(e.SALARY) FROM EMPLOYEE e GROUP BY e.DEPARTMENT The results are: DEPARTMENT AVG(SALARY) Coffee Room 950 Mail Room 1100 The Closet with the Light Out 850 Sub-Queries Sub-queries are permitted as deep as the database implementation being queried allows. For example, you could use the following sub-query (in bold) specified in ejb-jar.xml.
D y n a m ic Q u e r ie s Dynamic queries don't need to be added to the deployment descriptor. They are declared in the bean class for dynamic ejbSelects, or in the local or remote home interfaces for dynamic finders. A finder method for a dynamic query is: public java.util.Collection findDynamic(java.lang.String ejbql, Class[] types, Object[] args) throws javax.ejb.FinderException The ejbSelects for dynamic queries are: public java.util.Collection selectDynamicLocal(java.lang.
D y n am ic Q ue r i es Note A problem with your SQL may generate an exception which can potentially crash the system. You specify your own optimized SQL in the Borland proprietary deployment descriptor, ejb-borland.xml. The XML grammar is identical to that found in ejbjar.xml, except that the element is replaced with a element. This proprietary element contains a SQL-92 statement (not an EJB-QL statement) that is used to access the database instead of the CMP enginegenerated SQL.
C o nt a i ne r - m a na g e d d a t a ac c e s s s u pp o r t Container-managed data access support For CMP, the Borland EJB Container supports all data types supported by the JDBC specification, including types beyond those supported by JDBC. The following table shows the basic and complex types supported by the Borland EJB Container: Basic types: Complex types: boolean Boolean byte Byte char Character double Double float Float int Integer long Long short Short String java.sql.
C o nt ai n er - m a n ag e d da t a a c c e s s s up p o rt Support for Oracle Large Objects (LOBs) There are two types of Large Objects (LOBs), Binary Large Objects (BLOBs) and Character Large Objects (CLOBs). BLOBs are mapped to CMP fields with the following data types: ■ byte[] ■ java.io.Serializable ■ java.io.InputStream CLOBs, by virtue of being Character Large Objects, can only be mapped to cmp-fields with the java.lang.String data type.
C o nt a i ne r - m a na g e d d a t a ac c e s s s u pp o r t The following table shows the names or values for the different dialects (case is ignored for these values): Database Name Dialect Value JDataStore jdatastore Oracle oracle Sybase sybase MSSQLServer mssqlserver DB2 db2 Interbase interbase Informix informix C h ap t e r 1 7: E J B - Q L a n d Da t a A c c e s s S u p po r t 189
190 B E S D e ve l op e r ’s G u id e
Chapter 18 Generating Entity Bean Primary Keys Chapter 18 Each entity bean must have a unique primary key that is used to identify the bean instance. The primary key can be represented by a Java class, which must be a legal value type in RMI-IIOP. Therefore, it extends the java.io.Serializable interface. It must also provide an implementation of the Object.equals(Object other) and Object.hashCode() methods. Normally, the primary key fields of entity beans must be set in the ejbCreate() method.
G en e r at in g pr i m a r y k ey s f r om a us e r c la s s Generating primary keys from a user class With enterprise beans, the primary key is represented by a Java class containing the unique data. This primary key class can be any class as long as that class is a legal value type in RMI-IIOP, meaning it extends the java.io.Serializable interface. It must also provide an implementation of the Object.equals(Object other) and Object.
I m p le m e n t in g p r im a r y k e y g en e r at i o n by t he C M P en g in e The CMP engine would execute this SQL and then extract the appropriate value from the ResultSet. This value will then be used as the primary key when performing the subsequent INSERT. The extraction from the ResultSet is based on the primary key's type SQL Server: using getPrimaryKeyAfterInsertSql and ignoreOnInsert Two properties need to be specified for cases involving SQL Server.
I m pl e m en t i ng p r im ar y k e y g e ne r a t io n b y t h e CM P e ng in e autoPkGenerator java.lang.String NAMEDSEQUENCETABLE namedSequenceTableName java.lang.String TAB_A_SEQ keyCacheSize java.lang.
Chapter 19 Chapter 19 Transaction management This chapter describes how to handle transactions. Important For documentation updates, go to www.borland.com/techpubs/bes. Understanding transactions Application programmers benefit from developing their applications on platforms such as Java 2 Enterprise Edition (J2EE) that support transactions.
U n de r s t a n di n g t ra n s a c t io n s ■ Atomicity ■ Consistency ■ Isolation ■ Durability These characteristics are denoted by the acronym ACID. A transaction often consists of more than a single operation. Atomicity requires that either all or none of the operations of a transaction are performed for the transaction to be considered complete. If any of a transaction's operations cannot be performed, then none of them can be performed. Consistency refers to resource consistency.
T r an s a c t io n m an a g er s e r v ic e s use declarative transactions where the J2EE Container transparently starts and stops transactions. Transaction manager services There are two transaction managers, or engines, available in BES: ■ Transaction Manager (formerly known as Partition Transaction Service) ■ OTS (formerly known as 2PC Transaction Service) A Transaction Manager exists in each BES Partition. It is a Java implementation of the CORBA Transaction Service Specification.
T ra n s a c t io n m a na g e r s er v i c es Note Although support is provided by BES for two-phase commit transactions, they are inherently expensive due to number of remote procedure calls (RPCs) and should be used only when needed. Go to, “When to use two-phase commit transactions” on page 198. There are two steps to a two-phase commit. The first step is the preparation phase.
T r an s a c t io n m an a g er s e r v ic e s needed, therefore avoiding unnecessary RPCs involving JTA XAResource objects and the OTS engine, greatly improves your application's performance. Using multiple JDBC connections for access to multiple database resources from a single vendor in the same transaction: In scenarios involving multiple databases from a single vendor, it is often possible to avoid using two-phase commit.
T ra n s a c t io n m a na g e r s er v i c es transaction, the OTS engine is needed to reliably complete the transaction using the two-phase commit protocol. Sample scenarios include: ■ A session bean accesses two types of entity beans in a transaction where each are persisted in a different database. ■ A session bean accesses an entity bean and in the same transaction does some messaging work, such as sending a message to a JMS queue.
T r an s a c t io n m an a g er s e r v ic e s beans that have ejb.transactionManagerInstanceName set go to the (non-default) OTS engine. Other beans in the Partition that require method invocation in a transaction, but do not require 2PC, always find the Transaction Manager due to local service affinity. Following is a deployment configuration usage example. Displayed below is an extract from deployment descriptor ejb-borland.xml packaged with the deployed EJB module and viewable in the DDEditor. The ejb.
T ra n s a c t io n m a na g e r s er v i c es The example archive used is complex.ear, in a BES Partition. It has three beans: ■ OrderSesEJB: takes orders from customers, creates an order in the database, and sends messages to the manufacturers for making parts. ■ UserSesEJB: creates new users in the company database. Only accesses a single database, therefore only needs to access a 1PC engine (Transaction Manager).
D e cl a r at i v e t ra n s a c t io n m an a g em e n t in E n t e r pr i s e J a v a B ea n s Example 2PC usage 1 (A) The client calls OrderSesEJB.create() method to create a new order. 2 (B) Since the bean is configured to use the OTS engine named TwoPhaseEngine, the container locates the right transaction service named TwoPhaseEngine, and uses it for beginning the transaction. 3 (C) The session bean does some database work, and sends a message to a JMS queue.
D e c la r at iv e t r a ns a c t i o n m an a ge m e n t i n E nt er p r is e J a v aB ea n s EJBs utilize a declarative style of transaction management that differs from the traditional transaction management style. With declarative management, the EJB declares its transaction attributes at deployment time.
D e cl a r at i v e t ra n s a c t io n m an a g em e n t in E n t e r pr i s e J a v a B ea n s Whenever possible, enterprise beans should use container-managed transactions as opposed to bean-managed transactions. Container-managed transactions require less programming work and are less prone to programming error. In addition, a container-managed transaction bean is easier to customize and compose with other beans.
D e c la r at iv e t r a ns a c t i o n m an a ge m e n t i n E nt er p r is e J a v aB ea n s Transaction attributes EJBs that use bean-managed transaction have transaction attributes associated with each method of the bean. The attribute value tells the container how it must manage the transactions that involve this bean. There are six different transaction attributes that can be associated with each method of a bean. This association is done at deployment time by the Application Assembler or Deployer.
P r og r a m m a t ic t r a n s ac t i o n m a n a ge m e n t us i ng J T A A P I s about transaction synchronization and implements the javax.ejb.SessionSynchronization interface, then the Assembler/Deployer can specify only the attributes Required, RequiresNew, or Mandatory. These attributes ensure that the container invokes the bean only within a global transaction, because transaction synchronization can only occur within a global transaction.
J D B C A P I M o di f i c a t i on s JDBC API Modifications The standard Java Database Connectivity (JDBC) API is used by BES to access databases that support JDBC through vendor provided drivers. Requests for access to a database is centralized through the BES JDBC Connection Pool. This section describes modifications the BES JDBC pool makes to JDBC behavior for transactions. The JDBC pool is a pseudo JDBC driver that allows a transactional application to obtain a JDBC connection to a database.
H a n dl in g of E JB ex c e p t io n s If a global transaction is associated with the current thread of execution do not use this method. If the global transaction is not a container-managed transaction, that is the application manages its own transactions, and a commit is required use the JTA API to perform the commit rather than invoking commit() directly on the JDBC connection. Java.sql.Connection.
H a nd l in g of E J B e x c e pt io ns errors, transcend the application itself and can be handled by the application, the bean, or the bean container. The EJB declares application-level exceptions and system-level exceptions in the throws clauses of its Home and Remote interfaces. You must check for checked exceptions in your program try/catch block when calling bean methods. System-level exceptions An EJB throws a system-level exception, which is a java.ejb.EJBException (but may also be a java.rmi.
H a n dl in g of E JB ex c e p t io n s transaction rollback, they do not automatically mark the transaction for rollback. You often have the option to retry the transaction, though there are times when you must abort and rollback the transaction. The bean Provider is responsible for ensuring that the state of the bean is such that, if the client continues with the transaction, there is no loss of data integrity.
H a nd l in g of E J B e x c e pt io ns The client can also throw its own checked exception or re-throw the original exception. By throwing an exception, the client lets other programs further up the transaction chain decide whether or not to abort the transaction. However, in general it is preferable for the code or program closest to the occurrence of the problem to make the decision about saving the transaction. Lastly, the client can continue with the transaction.
Chapter 20 Message-Driven Beans and JMS Chapter 20 Important For documentation updates, go to www.borland.com/techpubs/bes. JMS and EJB According to the EJB 2.0 specification, there are no limitations on a bean acting as a JMS message producer or synchronous consumer. It can use the regular JMS APIs to send a message to a queue or publish to a topic. As long as you perform synchronous style consumption of messages (that is, not based on javax.jms.
C li e nt V ie w o f a n M D B have an EJB be driven asynchronously by that message. In turn, that EJB can send a message to another EJB or perform direct data access or other business logic. The caller does not wait beyond the time the message is successfully queued. On the other side, the EJB can process the message at its convenience.
N a m in g S u pp o r t an d C on f i gu r a t io n Naming Support and Configuration Since MDBs have no interfaces, MDBs do not have JNDI names in the normal sense like EJBHome objects do. Instead, they are associated with two objects that must preexist in JNDI before the MDB is deployed.
N a m in g S u p po r t a n d Co n f ig u r at io n MyMDBTopic ... serial://resources/tcf Now, we need to specify the JNDI name of the individual queue or topic. This is done with the element. Let's have a look at its DTD entry. This is yet another simple element.
Cl us t er i ng o f M D B s Clustering of MDBs The clustering of MDBs differs from the clustering of other enterprise beans. With MDBs, producers put messages into a destination. The messages will reside in the destination until a consumer takes the messages off the destination (or, if the messages are non-durable, when the server hosting the destination crashes). This is a pull model since the message will just reside on the destination until a consumer asks for it.
E r r o r R ec o v e r y consumption of a message, then you should consider deploying a queue rather than a topic. Error Recovery The following section deals with JMS server connection failures and setting connection rebind attempt properties. It also covers the redelivery of messages to the JMS service when an MDB fails to consume a message. The section on redelivery covers setting the redeliver attempt property as well as two properties for delivering messages to a dead queue.
E r r o r R e co v e r y ■ ejb.mdb.unDeliverableQueue: looks up the JNDI name of the queue.
M D B s a n d t r a ns a c t i on s MDBs and transactions See Chapter 23, “Using JMS” for information on using JMS within transactions. This section deals exclusively with using MDBs in transactions. The most common scenario of using MDBs in transactions is the desire to have two-phase commit (2PC) completion of transactions started for the onMessage() method. Such an MDB will have the REQUIRED transaction attribute.
Chapter 21 Chapter 21 Connecting to Resources with BES: using the Definitions Archive (DAR) J2EE specifies a uniform mechanism to establish connections to relational databases using JDBC datasources, message brokers using JMS resource objects, and general Enterprise Information Systems (EIS) using Connectors resource adapters. JNDI bound objects called resource connection factories are used to implement this mechanism.
J N D I D e f in it io n s M o du l e 1 If any external drivers are needed, which is usually the case, they must be deployed to the target Partition as a library archive. See User's Guide, Using Partitions chapter, for information on deploying to Partitions. Note that this step is not necessary if you are using the native all-Java database, JDataStore as your backend, or the JMS services broker.
You can create a new DAR by simply providing a descriptor file in the directory structure above, JARing it into a DAR, and deploying it to a Partition using the server's tools. Or, you can run the DDEditor and select File|New|JNDI Definitions Module and allow the DDEditor to walk you through the creation procedure from scratch. Or, of course, you can edit the existing one. Migrating to DARs from previous versions of Borland Enterprise Server Previous product versions, including IAS 4.1 and BAS 4.
D is a b li n g a n d E n ab li n g a J N D I D e f i ni t io n s M o d ul e Select the JNDI Definitions tab and select JNDI Definitions Archive to create the new DAR. Click OK. You may now add JDBC datasources or add JMS resources, or you can do this later. When you are finished save the module by choosing "File|Save..." . After saving the archive, use the J2EE Deployment Wizard to deploy the module.
the default naming space for datasource objects. However, any plain Java object that implements both java.io.Serializable and javax.naming.Referenceable can be stored under this special JNDI URL context. Configuring persistent storage locations for Serial Context By default the Partition's Naming Service persistently stores JNDI objects in a particular default location on disk (/var/domains/base/ configurations//mos//adm/ vbroker.
226 B E S D e ve l op e r ’s G u id e
Chapter 22 Using JDBC Chapter 22 Datasources are bound into a JNDI service after the JNDI Definitions Module is deployed. Datasource objects are stored into the Serial Context provider in the naming service. The portable J2EE mandated way to lookup a datasource is using a Resource Reference in the individual component's ejb-jar.xml descriptor file. Refer to the J2EE 1.3 Specification for information on how to use this element.
C o nf ig u ri n g J D B C D a t a s ou r c e s Configuring JDBC Datasources Using the Console, navigate to the "Deployed Modules" list in the Partition whose datasources you need to configure. By default, every Partition has a predeployed JNDI Definitions Module (DAR) called default-resources.dar. Right-click on the module and choose "Deployment Descriptor Editor" from the context menu. The Deployment Descriptor Editor (DDEditor) appears.
C o nf i g ur i ng J D B C D a t a s ou r c e s The Main tab in the content pane captures the essential properties needed to define the chosen database. If the database is known to the DDEditor, it will automatically complete these properties.
C o nf ig u ri n g J D B C D a t a s ou r c e s The Driver Properties and Pool Properties tabs capture some of the information from the Main tab, but also allow you to set any less common properties that do not appear in the Main tab. Too add pool properties, click the Add button and select the property you want to add from the drop-down list under "Name.
C o nf i g ur i ng J D B C D a t a s ou r c e s below in “Defining the Connection Pool Properties for a JDBC Datasource” on page 232. The same procedure is used for adding Driver Properties. Consult your database documentation for any properties you need to define. Once you're finished, save the module and dismiss the final modal window. The JNDI Definitions Module is automatically re-deployed to the Partition.
D e f in i ng t h e C on n e c t io n P o ol P r o pe r t i es f or a J D B C D a t a s ou r c e Defining the Connection Pool Properties for a JDBC Datasource At runtime each JDBC datasource corresponds to an instance of a connection pool. Connection pools provide for the reuse of connections and optimization of database connectivity. Some datasources may require different treatment as connection pools than others. A number of configuration options exist for these connection pools.
D e f in in g t h e C o nn e c t io n P o o l P ro p e rt ie s f o r a J D B C D a t a s ou r c e value> elements shown above. The complete list of properties, allowed values, defaults, and descriptions appear in the following table: Name Allowed Values optimizeXA Boolean waitTimeout Integer Indicates type transaction association of all connections Enumera retrieved from the ted: connection pool, ■ Direct whether "Direct" or "XA" ■ XA Not Applicable.
D e f in i ng t h e C on n e c t io n P o ol P r o pe r t i es f or a J D B C D a t a s ou r c e Name Allowed Values idleTimeout Integer dialect Enumerat ed: ■ oracle ■ sybase ■ interba se ■ jdatast ore Indicates type transaction association of all connections Enumera retrieved from the ted: connection pool, ■ Direct whether "Direct" or "XA" ■ XA Not Applicable.
D e f in in g t h e C o nn e c t io n P o o l P ro p e rt ie s f o r a J D B C D a t a s ou r c e Name Allowed Values Description Default Value connect ionType Indicates type transaction association of all connections Enumera retrieved from the ted: connection pool, ■ Direct whether "Direct" or "XA" ■ XA Not Applicable. Property specification is mandatory reuseStateme nts Boolean Optimization directive requesting prepared SQL statements to be cached for reuse.
D e f in i ng t h e C on n e c t io n P o ol P r o pe r t i es f or a J D B C D a t a s ou r c e Name resSharingSc ope Allowed Values Enumerat ed: ■ Shareab le ■ Unshare able Description Indicates whether connection statements and result sets are cached for reuse -Shareable -- thereby optimizing throughput of connections. If set to Unshareable, connections are closed once the application closes the connection.
D e f in in g t h e C o nn e c t io n P o o l P ro p e rt ie s f o r a J D B C D a t a s ou r c e Name maxPreparedS tatementsPer Query Allowed Values Integer Description Under certain conditions such as high concurrency or when CMP 2.0 entity beans are processed, more than one PreparedStatement can be processed concurrently for the same SQL query on the same pooled connection. For example, a SQL query SELECT name FROM table1 WHERE id=? can return distinct result sets when different values are used for ?.
G et t in g d eb u g ou t p u t Getting debug output A number of system properties can be set to log activity at datasource, connection pool, connection and statement levels during application processing. It is not necessary to configure these properties during normal application runtime execution but should a situation arise where details of JDBC flow of control is needed these options are useful.
S u p po r t f o r ol d er J D B C 1 . x d r iv e r s ■ Prepared: a connection that was associated with a transaction received a prepare() call from the transaction service ■ Forgot: a connection that was associated with a transaction received a forget() call from the transaction service ■ TxBusyXaStart: a pooled connection that is associated with a transaction branch.
A d v a nc e d T o p ic s f or D e f i ni ng J D B C D a t a s ou r c e s Advanced Topics for Defining JDBC Datasources Whether you choose to use the server's graphical tools or not, defining a datasource means providing some information to the container in XML format. Let's look at what it takes to define a JDBC datasource and bind it to JNDI. Let's start by examining the DTD of the jndi-definitions.xml file. The elements in bold are the main elements specific to JDBC datasources.
A d v a nc e d T o pi c s f o r D e f in i ng J D B C D a t a s ou r c e s connectionType Enumerated Direct ... //other properties as needed ... ... We're not done. Now we must perform the other half of the datasource definition by providing information on the driver.
C o nn e c t i ng t o J D B C R e s ou r c e s f r om A p pl ic a t i on C o m p on e nt s Note the driver datasource JNDI name in bold. Now we'll add the following: serial://datasources/OracleDriver oracle.jdbc.pool.
C o nn e c t in g t o J D B C Re s o ur c e s f r o m A p p lic a t i o n C o m p on e n t s Let's look at an example entity bean that uses the Oracle datasource we defined above: entity_bean ... jdbc/MyDataSource serial://datasources/Oracle True ...
244 B E S D e ve l op e r ’s G u id e
Chapter 23 Using JMS Chapter 23 JMS connection factories are bound into a JNDI service after the JNDI Definitions Module is deployed. Connection factory objects are stored into the Serial Context provider in the naming service. The portable J2EE mandated way to look up a datasource is using a Resource Reference in the individual component's ejb-jar.xml descriptor file. Refer to the J2EE 1.3 Specification for information on how to use this element.
C o nf ig u ri n g J M S C on n e c t io n F a c t o r ie s a nd D e s t in a t i on s Configuring JMS Connection Factories and Destinations Using the Management Console, navigate to the "Deployed Modules" list in the Partition whose JMS connection factories you need to configure. By default, every Partition has a predeployed JNDI Definitions Module (DAR) called default-resources.dar. Right-click on the module and choose "Edit deployment descriptor" from the context menu.
J M S a n d T r an s a c t io n s A dialog box prompts for a JNDI name for JMS object that is to be created. Once given, a representation of this JMS object appears in the tree in the Navigation Pane. Click its representation to open its configuration panel. The DDEditor has knowledge of Tibco and Sonic, and can auto fill the class names for the appropriate JMS object. Note The Main panel will not suggest any JMS objects other than Tibco or Sonic.
J M S an d T r a n s ac t io ns session is transacted, but provide 0 for the value of the acknowledgment mode. The Bean Provider should not use the JMS acknowledge() method either within a transaction or within an unspecified transaction context. Message acknowledgment in an unspecified transaction context is handled by the container. Section 17.6.5 describes some of the techniques that the container can use for the implementation of a method invocation with an unspecified transaction context.
E na b li ng t h e J M S s er v i c es s e c ur i t y // execute JDBC work java.sql.Connection dbConn = datasource.getConnection(); // execute SQL // call some other EJBs in the same transaction // grab a reference to an EJB Remote interface ejbRemote.doWork(); // send a JMS message to a queue jmsSender.send(msg); } All the operations execute as a single unit of recoverable work (transaction) and leverages resource connection pooling (JDBC pool, JMS pool, and so forth).
C o nn e c t i ng t o J M S Co n n ec t i o n F a c t o ri e s f r o m A p pl ic a t i on C o m p on e n t s datasource-class-name (#PCDATA)> log-writer (#PCDATA)> class-name (#PCDATA)> You only need to define the element to register the JMS connection factory with JNDI.
C on n e c t in g t o J M S Co n ne c t i o n F a c t or i es f r om A p pl ic a t i on C o m p on e n t s ... jms/MyJMSQueueConnectionFactory javax.jms.QueueConnectionFactory Container Shareable jms/MyJMSQueue javax.jms.Queue ...
C o nn e c t i ng t o J M S Co n n ec t i o n F a c t o ri e s f r o m A p pl ic a t i on C o m p on e n t s jms/MyJMSQueueConnectionFactory serial://resources/qfc jms/MyJMSQueue serial://resources/q ...
Chapterb 24 JMS provider pluggability Chapter 24 Important For documentation updates, go to www.borland.com/techpubs/bes. BES is designed to support any arbitrary JMS provider as long as some requirements are met. There are three levels of JMS pluggability: runtime pluggability, configuration of JMS admin objects (connection factories and queues/topics), and service management.
R u nt im e p lu g g ab il it y queue or topic must be a transactional resource. BES requires that JMS products implement the JTA XAResource interface and support JMS XA APIs. In addition, the JMS product should support the javax.jms.ConnectionConsumer interface. The latter is vital since a central idea of MDBs is the concurrent consumption of messages. The ConnectionConsumer interface achieves this. The mechanism also works in conjunction with some optimal methods of the javax.jms.
C o nf ig u ri n g a d m i n o b je c t s ConnectionConsumer interface since a central idea of MDBs is the concurrent consumption of messages. The ConnectionConsumer achieves this, and works in conjunction with some optimal methods of the javax.jms.Session objects. Tibco and Sonic Tibco and Sonic have already achieved the runtime level of pluggability. Additionally, BES 6.0 passed CTS 1.3.1 on both JMS providers.
C o nf ig u ri n g a d m i n o b je c t s 7 To add additional properties for the JMS object, select the Properties tab and click "Add" to add properties (name, type, value). Tibco Admin Console BES includes the Tibco Admin Console for additional configuration. To launch the Tibco Admin Console, select it from the Tools menu in the BES Management Console. Configuring admin objects for other JMS providers BES provides configurations in the DDEditor for Tibco, Sonic and other JMS providers.
C o nf ig u ri n g a d m i n o b je c t s word,connectID,clientID,sequential,loadBalancing Sonic.XATopicConnectionFactory.props=connectionURLs,defaultUser,defaultPass word,connectID,clientID,sequential,loadBalancing Sonic.Queue.props=queueName Sonic.Topic.props=topicName Other.QueueConnectionFactory.props= Other.TopicConnectionFactory.props= Other.XAQueueConnectionFactory.props= Other.XATopicConnectionFactory.props= Other.Queue.props= Other.Topic.props= Tibco.QueueConnectionFactory.class=com.tibco.tibjms.
C o nf ig u ri n g a d m i n o b je c t s userPassword=String address=String Service management for supported and other JMS providers Service management is handled by the BES service control infrastructure. JMS service processes like starting, stopping and server configuration are provided in the managed object configuration for supported (Tibco and Sonic) JMS providers out of the box. This level of pluggability for other JMS providers can be achieved with some configuration.
C o nf ig u ri n g a d m i n o b je c t s 9 If the JMS server is an all Java server, repeat steps 3 through 5 to create a launcher for the Admin Console. Required libraries for other JMS providers When trying to connect to another JMS provider the required libraries must first be deployed to the target Partition. The steps are: 1 Start your BES server and Management Console. 2 From the Console, open the Wizards menu and select the Deployment Wizard.
C r e at in g a c l u s t e re d J M S s e r v ic e Sonic Using the DDEditor, you can configure a name (JMS service URL, sequential, loadBalancig) a type, and a value in the XML , as shown in the example below: serial://jms/message progress.message.jclient.
C r e at in g a c l u s t e re d J M S s e r v ic e 2 Right-click the your Configuration and select Add Managed Object from Template/jms/Clustered Tibco. 3 Select a group to add clustered Tibco to from the drop-down menu. 4 Make the following changes to the template properties for the second Tibco server: ■ 2nd Management Agent=hub.name where hub.name is the name of your Management Hub. ■ Name - this is the name of the second Tibco server.
C r e at in g a c l u s t e re d J M S s e r v ic e initial-monitor="true" type="redundancy-group"> Note The Tibco servers in the example above are running on different hosts.
E n a b lin g s e c ur i t y f o r J M S Sonic Use the Sonic Wizard to create a Managed Sonic Messaging Service. For details on the specifics of your Sonic Messaging Service, refer to the Sonic documentation. For clustering Sonic, you have two choices: ■ If you have already used the Sonic Wizard to create a managed Sonic service, check the box and choose the appropriate instance from the drop down list. ■ You can create a new managed Sonic service by clicking the Launch Sonic Wizard button.
E n a b lin g s e c ur i t y f o r J M S Sonic To enable and disable security for Sonic, you must ensure db.ini file is updated before initialization of the database. There are two levels at which security must be applied, the backend database and the Sonic Broker. Use the Management Console to configure Sonic Broker and you can use a dbtool command to take care of the database. Most importantly, the database and Sonic broker must be in sync.
E n a b lin g s e c ur i t y f o r J M S 5 On the Manage tab of the Sonic Explorer console, navigate to the Sonic server in the container where it is deployed. 6 Right-click on the container that hosts the Sonic server that is being security enabled and choose Operations > Shutdown. 7 From the command line issue dbtool/ r b from /bin directory.
266 B E S D e ve l op e r ’s G u id e
Chapter 25 Implementing Partition Interceptors Chapter 25 Implementing Partition Interceptors requires the following steps: 1 Defining your interceptor using the module-borland.xml descriptor file. 2 Creating the interceptor class. 3 JARing the class and the descriptor file. 4 Deploy the JAR to the Partition of interest. Important For documentation updates, go to www.borland.com/techpubs/bes. Defining the Interceptor You define the interceptor by creating a module-borland.xml file.
C r e at in g t he I n t e r c ep t o r C la s s The element is an optional field that controls the order in which a set of interceptors for a particular Partition are fired. This value must be between 0 and 9. Priority 0 ranks before priority 9. Interceptors are fired in order during load time and in reverse order during shutdown. If two or more interceptors share the same priority, there is no way to determine or enforce which of that set will be fired relative to the other.
C r e at in g t he I n t e r c ep t o r C la s s public void startupPostLoad(); This method is invoked after all Partition services have loaded their respective modules. public void shutdownPreUnload(); This method is called before the Partition services unload their respective modules. The parameter now reverses its meaning; priority 9 interceptors are called first, then priority 8, and so forth.
C r e at in g t he J A R f il e // There is no requirement to log. System.out.println(_className + ": shutdownPreUnload"); } public void shutdownPostUnload() { // Writing to System.out and System.err will // cause the output to be logged. // There is no requirement to log. System.out.println(_className + ": shutdownPostUnload"); } public void PartitionTerminating() { // Writing to System.out and System.err will // cause the output to be logged. // There is no requirement to log. System.out.
Chapter 26 VisiConnect overview Chapter 26 Important For documentation updates, go to www.borland.com/techpubs/bes. J2EE™ Connector Architecture In the information technology environment, enterprise applications generally access functions and data associated with Enterprise Information Systems (EIS). This traditionally has been performed using non-standard, vendorspecific architectures.
C o m p on e nt s the Borland Enterprise Server. With VisiConnect, the Borland Enterprise Server ensures access to heterogeneous EISs. In turn, the EIS vendors need provide only one standard Connectors-compliant resource adapter. By default, this resource adapter has the capability to deploy to the Borland Enterprise Server. Components The Connectors environment consists of two major components - the implementation of the Connectors in the application server, and the EISspecific Resource Adapter.
S y s t e m Co n t r a c t s A Resource Adapter is a system-level driver specific to an EIS, which provides access to that EIS. To put it simply, a Resource Adapter is analogous to a JDBC driver. The interface between a Resource Adapter and the EIS is specific to the EIS. It can be either a Java interface or a native interface.
S y s t em Co n t r a c t s the system-level issues related to EIS integration. This promotes the development of application components with greater ease and maintainability. VisiConnect, in compliance with the Connectors specification, has implemented the standard set of defined contracts for: ■ Connection Management, that allows an application server to pool connections to underlying EISs, providing application components with connection services to EISs.
S y s t e m Co n t r a c t s ■ Find the right connection to an EIS from an existing set of pooled connections, and reuse that connection. ■ Hook in Borland Enterprise Server's transaction and security management. The Borland Enterprise Server establishes, configures, caches and reuses connections to the EIS automatically through VisiConnect.
S y s t em Co n t r a c t s ■ Local Transaction support: the application server manages resources directly, which are local to the Resource Adapter. Unlike XA Transactions, local transactions can neither participate in the two-phase commit (2PC) protocol, nor participate as a distributed transaction (whereas the transaction context is simply propagated); instead, local transactions solely target one-phase commit (1PC) optimization.
S y s t e m Co n t r a c t s sign-on. If the component has specified explicit security information, this will be presented in the call to obtain the connection, even in the case of container-managed sign-on. Component-Managed Sign-on When employing component-managed sign-on, the component provides all the required security information - most commonly a username and a password - when requesting to obtain a connection to an EIS.
S y s t em Co n t r a c t s ■ Certificate authentication: when an SSL or HTTPS client request is initiated, Borland Enterprise Server responds by presenting its digital certificate to the client. The client then verifies the digital certificate and an SSL connection is established.
Co m m o n C lie n t I n t e r f a c e ( C C I ) resource role to be used when allocating managed connections and connection handles. A default resource role can be defined for the connection factory in the security-map element. To do this, specify a user-role value of "*" and a corresponding resource-role value. The defined resource-role is then utilized whenever the current identity if not matched elsewhere in the Security Map. This is an optional element.
C o m m o n Cl ie n t I n t e r f a c e ( CC I ) directly with the Borland Enterprise Server; this provides for a smoother, less costly migration path to J2EE 1.3. The CCI defines a remote function call interface that focuses on executing functions on an EIS and retrieving the results. The CCI is independent of a specific EIS; in other words, it is not bound to the data types, invocation hooks, and signatures of a particular EIS. The CCI is capable of being driven by EISspecific metadata from a repository.
P ac k a g in g an d De p lo y m e n t setRecordName() and setRecordShortDescription() get and set the record data. You must create records for all of the data structures that are externalized by the EIS functions you want to reuse. You then use the records as input and output objects that pass data via a Resource Adapter to and from an EIS.
P a c k a gi n g an d D ep l oy m e n t Figure 26.2 Packaging and Deployment in the Borland Enterprise Server and VisiConnect A Resource Adapter packages a set of Java interfaces and classes, which implement the Connectors-specified system contracts and EIS-specific functionality to be provided by the Resource Adapter.
V i s iC o nn e c t F e at u r e s VisiConnect Features Among the value-added features provided by VisiConnect as enhancements to the Connectors standard are the following: ■ VisiConnect Container ■ Local and Remote Connectors Support ■ Additional Classloading Support ■ Secure Password Credential Storage ■ Connection Leak Detection ■ Security Policy Processing of ra.
V i s iC o nn e c t F ea t u r e s Local Connectors are used with most J2EE Applications, while Remote Connectors are mainly used in the following cases: ■ Migrating a non-J2EE application to J2EE, where it is required to interface the legacy application to Connectors as a migration step ■ Running a non-J2EE application outside the aegis of an Application Server, where it is required to interface the application with Connectors ■ Running CORBA clients/servers which are required to interface with Conne
R es o u r c e A d ap t e r s You specify a reference to the RAR Java classes by adding a ClassPath= entry in the RAR Manifest.mf file. You can also store the EJB Java classes in the same JAR file that is contained within the EAR. This scenario provides a "support" JAR file that contains Java classes for the components in the EAR that require them.
286 B E S D e ve l op e r ’s G u id e
Chapter 27 Using VisiConnect Chapter 27 The Java 2 Enterprise Edition (J2EE) Connector Architecture enables EIS vendors and third-party application developers to develop Resource Adapters that can be deployed to any application server supporting the J2EE 1.3 Platform Specification. The Resource Adapter provides platform-specific integration between the J2EE component and the EIS.
V i s iC o nn e c t C o nt ai n er Container Overview The VisiConnect Container is a complete implementation of the Connectors 1.0 specification, including all optional functionality. Every Resource Adapter object in the deployed Connector is simultaneously both a Resource Adapter object and a CORBA object. The VisiConnect Container can be deployed as a standalone, 100% pure Java service or as a fully-distributed deployment.
C on n e c t io n M a n a ge m e n t from your Java interfaces for use in other languages. To a CORBA client, the VisiConnect Container is a CORBA server. The VisiConnect Container tools are CORBA tools that are equally capable of handling Resource Adapters. The Borland VisiConnect Container is based on JNDI over CosNaming and JTS/OTS. Together, these provide complete support for CORBA.
C o nn e c t i on M a n ag e m e nt the ra.xml file. If the configuration property names match, VisiConnect uses the property-value for the corresponding configuration property name. Minimizing the Runtime Performance Cost Associated with Creating Managed Connections Creating Managed Connections can be expensive depending on the complexity of the Enterprise Information System (EIS) that the Managed Connection is representing.
C on n e c t io n M a n a ge m e n t You configure this setting using the maximum-capacity element in the raborland.xml descriptor file. If a new Managed Connection (or more than one Managed Connection in the case of capacity-delta being greater than one) needs to be created during a connection request, Borland Enterprise Server ensures that no more than the maximum number of allowed Managed Connections are created.
S e c u r it y M an a ge m e n t w it h t he S e c u r it y M ap Garbage Collection VisiConnect automatically detects connection leaks by leveraging its Java Virtual Machine (JVM) garbage collector mechanism. When an application component terminates and the connections it uses become de-referenced, the garbage collector calls the connection object's finalize() method.
S ec u r it y M an a ge m e n t w it h t h e S e c u r it y M a p time is found in the mapping, the associated resource role is used to provide security information for interacting with an EIS. The use-caller-identity option is used when user identities in the user role identified at run time are available to the EIS as well.
S e c u r it y M an a ge m e n t w it h t he S e c u r it y M ap Default Roles In addition, the element enables the definition of a default user role that can be associated with the appropriate resource role. This default role would be preferred to if the user role identified at run-time is not found in the mapping. The default user role is defined in the element with an element given a value of "*".
S ec u r it y M an a ge m e n t w it h t h e S e c u r it y M a p where: -rolename Resource role name to store in the resource vault. -usermame Resource username to associate with the resource role. -password Resource password to associate with the resource role. -vaultfile (optional) Path to the vault file you write the resource role(s)to.
S e c u r it y M an a ge m e n t w it h t he S e c u r it y M ap VisiConnect will use the vault if Security Map information is specified in at deployment time for a Resource Adapter. If the resource vault is password protected, VisiConnect will need to have the following property passed to it: -Dvisiconnect.resource.security.vaultpwd= If the resource vault is in a user specified location (-vaultfile ...), VisiConnect will need to have the following property passed to it: -Dvisiconnect.
Re s o ur c e A d ap t e r O v e r v ie w file itself is password protected, using the password "goofy". For VisiConnect to use this vault, the following properties must be set for it: -Dvisiconnect.resource.security.vaultpwd=goofy Example 3: java -Dborland.enterprise.licenseDir=/opt/BES/var/servers/servername/adm -Dserver.instance.root=/opt/BES/var/servers/servername -Dpartition.name=standard com.borland.enterprise.visiconnect.tools.
R e s ou r c e A d ap t e r O v er v i ew EISs. Resource Adapters encapsulate the Java components and, if necessary, the native components required to interact with the EIS. Development Overview See “Developing the Resource Adapter” on page 303, for more information. Developing a Resource Adapter from scratch requires implementing the necessary interfaces and deployment descriptors, packaging these into a Resource Adapter Archive (RAR), and finally deploying the RAR to the Borland Enterprise Server.
Re s o ur c e A d ap t e r O v e r v ie w ■ a JAR containing Java classes that implement the Resource Adapter ■ a META-INF directory containing the files Manifest.mf and ra.xml 1 Create the ra-borland.xml file using the Borland Deployment Descriptor Editor (DDEditor) and save it into the staging area's META-INF directory. See Using the Deployment Descriptor Editor in the Borland Enterprise Server User's Guide for information on using the DDEditor.
D e pl o y m e nt De s c r ip t o r s f o r t h e R es o u r c e A da p t e r 7 Create the Resource Adapter Archive: jar cvf resource-adapter-archive.rar -C staging-directory This command creates a RAR file that you can deploy to the server. The -C staging-directory option instructs the JAR command to change to the staging-directory so that the directory paths recorded in the RAR file are relative to the directory where the Resource Adapters were staged.
D e pl o y m en t D e s c r ip t o rs f or t h e R e s o ur c e A d ap t e r specified in this file in order to deploy the RAR file. This functionality is consistent with the equivalent .xml extensions for EJBs, EARs, WARs, and client components for the Borland Enterprise Server. Until Borland-specific deployment properties are provided in the ra.borland.xml file, the RAR cannot be deployed to the server. The following attributes must be specified first in ra-borland.
D e pl o y m e nt De s c r ip t o r s f o r t h e R es o u r c e A da p t e r values for configuration parameters which exist in the ra.xml deployment descriptor. A minimum set of this information is required for deployment. The following is an example of ra-borland.
D ev e lo p in g t h e R e s ou r c e A d ap t e r Configuring the Security Map To use container-managed sign-on, the Borland Enterprise Server must identify a resource role and then request the connection to the EIS on behalf of the resource role. To make this identification, the server looks for a security map specified with the element in the ra-borland.xml descriptor file.
D e v el o pi n g t he R e s ou r c e A d ap t e r ■ ManagedConnection.setLogWriter() ■ ManagedConnection.getLogWriter() The resource adapter must also provide a default implementation of the javax.resource.spi.ConnectionManager interface for cases in which the Resource Adapter is used in a non-managed two-tier application scenario. A default implementation of ConnectionManager enables the Resource Adapter to provide services specific to itself.
De p lo y in g t h e R e s ou r c e A d ap t e r ■ The Resource Adapter is required to support the security contract by implementing the ManagedConnectionFactory.createManagedConnection() method. ■ The Resource Adapter is not required to support re-authentication as part of its ManagedConnection.getConnection() method implementation. ■ The Resource Adapter is required to specify its support for the security contract as part of its deployment descriptor.
T he r a - bo r la n d . x m l de p lo y m e nt d es c r i pt o r D T D Resource Adapter. Borland Enterprise Server implicitly assigns a deployment name that matches the filename of the RAR file or deployment directory containing the Resource Adapter. This logical name can be used to manage the Resource Adapter after the server has started. The Resource Adapter deployment name remains active in the Borland Enterprise Server until the module is undeployed. The ra-borland.
T h e r a- b o r la nd . x m l d e p lo y m e nt d e s c ri p t or D T D The following table shows the DOCTYPE headers for both ra.xml and raborland.xml: Table 27.1 DOCTYPE headers Descriptor File DOCTYPE Header ra.xml ra-borland.xml
T he r a - bo r la n d . x m l de p lo y m e nt d es c r i pt o r D T D Element Hierarchy The element hierarchy of ra-borland.xml is as follows: Code sample ra-borland.
T h e r a- b o r la nd . x m l d e p lo y m e nt d e s c ri p t or D T D and either or The DTD
T he r a - bo r la n d . x m l de p lo y m e nt d es c r i pt o r D T D This is a required element. -->
T h e r a- b o r la nd . x m l d e p lo y m e nt d e s c ri p t or D T D This is a required element IF native libraries are present. -->
T he r a - bo r la n d . x m l de p lo y m e nt d es c r i pt o r D T D during resizing of the maintained connection pool. This is an optional element. Failure to specify this value will result in VisiConnect using its defined default value. Default Value: 1 -->
T h e r a- b o r la nd . x m l d e p lo y m e nt d e s c ri p t or D T D Failure to specify this value will result in VisiConnect using its defined default value. Value Range: true|false Default Value: false -->
T he r a - bo r la n d . x m l de p lo y m e nt d es c r i pt o r D T D This element allows for the specification of a defined set of user roles and the corresponding run-as roles (representing EIS identities) that should be used when allocating Managed Connections and Connection Handles. A default Resource run-as role can be defined for the Connection Factory via the map.
A p pl ic a t i on D e v el op m e n t O v e r v ie w -->
A p p li c at io n De v e lo p m e nt O v e r v ie w Template design pattern to these interfaces, refer to Section 5.5.1 in the Connectors 1.0 specification (http://java.sun.com/j2ee/connector).
A p pl ic a t i on D e v el op m e n t O v e r v ie w container terminates a component instance, the container cleans up all the connections used by that component instance. Non-Managed Application Scenario In the non-managed application scenario, a similar programming model must be followed in the application component.
A p p li c at io n De v e lo p m e nt O v e r v ie w javax.naming.Context ctx = new javax.naming.InitialContext(); javax.resource.cci.ConnectionFactory cxFactory = (javax.resource.cci.ConnectionFactory)ctx.lookup( "java:comp/env/shme/shmeAdapter" ); javax.resource.cci.Connection cx = cxFactory.getConnection(); // Create an Interaction instance javax.resource.cci.Interaction ix = ct.createInteraction(); // Create a new instance of the respective InteractionSpec com.shme.shmeAdapter.
A p pl ic a t i on D e v el op m e n t O v e r v ie w while ( iter != null && iter.hasNext() ) { // Get a record element and extract value ... } // Set up the requirements for the ResultSet returned by the execution of // an Interaction. This step is optional. Default values are used if // requirements are not explicitly set. com.shme.shmeAdapter.InteractionSpecImpl rsIxSpec = new com.shme.shmeAdapter.InteractionSpecImpl(); rsIxSpec.setFetchSize( 20 ); rsIxSpec,setResultSetType( javax.resource.cci.
A p p li c at io n De v e lo p m e nt O v e r v ie w // Create an empty CustomerRecord instance to hold output from // the execution of an Interaction CustomerRecord customer = // ... create an instance // Create a PurchaseOrderRecord instance as an input to the Interaction // and set properties on this instance. The PurchaseOrderRecord is another // example of a custom Record PurchaseOrderRecord purchaseOrder = // ... create an instance purchaseOrder.setProductName( "..." ); purchaseOrder.setQuantity( "..
A p pl ic a t i on D e v el op m e n t O v e r v ie w EJB 2.x example ejb-jar.xml deployment descriptor This example uses container-managed persistence
A p p li c at io n De v e lo p m e nt O v e r v ie w Remote s_exec_customer_query Required This corresponds to the ejb-jar.xml above.
A p pl ic a t i on D e v el op m e n t O v e r v ie w SHME Repository URL for Connector configuration repositoryUrl java.lang.String s_repository://S_APP01 Location of Resource Adapter configuration within the SHME Repository configurationUrl java.lang.
O t h er C o n s id e ra t i on s Other Considerations Converting a Local Connector to a Remote Connector VisiConnect is the sole Connector Container which supports RemoteConnectors. The issue of Remote Connectors is presently outside the Connectors specifications. As a result, most Resource Adapters available on the market are implemented as Local Connectors.
O t h e r C o ns i de r a t io n s com.borland.enterprise.visiconnect.DataSource or the com.borland.enterprise.visiconnect.cci.ConnectionFactory interfaces. 3 Update the classes in the ra.xml standard deployment descriptor file. For example, before extending the interfaces, the ra.xml may look something like this: com.borland.enterprise.connector.serial. LocalTxManagedConnectionFactory javax.sql.
O t h er C o n s id e ra t i on s mapping, which includes C, C++, Delphi (Object Pascal), Ada, COBOL, COBOL Scripting Language, Lisp, PL/1, Python, and Smalltalk. Working with Poorly Implemented Resource Adapters Some commercially available Resource Adapters may be poorly implemented.
O t h e r C o ns i de r a t io n s javax.naming.spi.ObjectFactory implemenation source Adapter with backup mechanism for JNDI Reference-based connection factory lookup. ■ The Resource Adapter which specifies an connection factory or connection interface while not implementing that interface in its connection factory or connection class, respectively. Section 10.6 "Resource Adapter XML DTD" in the Connectors spec discusses the related requirements. To illustrate, let's say that in the ra.
O t h er C o n s id e ra t i on s private javax.naming.Reference ref; // ... public javax.naming.Reference getReference() { // implement such that getReference() never returns null // ... return ref; } public javax.naming.Reference setReference( javax.naming.Reference ref ) // this.ref = ref; } // Also, when dealing with a poorly behaving getReference(), there are various ways to accomplish this, but principally, the idea is to implement getReference() such that it never returns null.
O t h e r C o ns i de r a t io n s if ( value != null ) { ref.add( new javax.naming.StringRefAddr( "connectionmanager-class", value ) ); } } return ref; } // ... } Then implement the associated object factory class, in this case: com.shme.shmeAdapter.GoodCFObjectFactory package com.shme.shmeAdapter; import javax.naming.spi.*; import javax.resource.spi.*; public class GoodCFObjectFactory implements ObjectFactory { public GoodCFObjectFactory() {}; public Object getObjectInstance( Object obj, javax.naming.
O t h er C o n s id e ra t i on s { String cxManagerStr = (String)ref.get( "connectionmanager-class" ).getContent(); Class cxmClass = Class.forName( cxManagerStr ); java.lang.ClassLoader cloader = cxmClass.getClassLoader(); refCm = (ConnectionManager)cxmClass.newInstance(); } GoodConnectionFactory cf = null; if ( refCm != null ) { cf = new GoodConnectionFactory( refMcf, refCm ); } else { cf = new GoodConnectionFactory( refMcf ); } return cf; } return null; } } Update the classes in the ra.
O t h e r C o ns i de r a t io n s Compile the Java code for the extended implementation (and any helper classes) into class files. Package these into the Resource Adapter's Java Archive (.jar) file. Update the Resource Adapter Archive (.rar) file with this extended .jar. Deploy the Resource Adapter Archive, or include it in an Enterprise Application Archive (.
332 B E S D e ve l op e r ’s G u id e
Chapter 28 Chapter 28 Apache Ant and running BES examples Many of the BES examples now employ the Ant build script system.
S y n t a x a n d g e n er a l us a g e Syntax and general usage The following table shows the currently defined tasks and their relationship to the equivalent commands. Ant Task Name Equivalent Command Line appclient appclient Function Fileset Attribute Runs a client application. iascompilejsp iastool -compilejsp Precompiles JSP's. iasdeploy iastool -deploy Deploys a J2EE module. iasgendeployable iastool gendeployable Generates a manually deployable module.
T r a n s la t i ng B E S c o m m a n ds i nt o A n t t a s k s Translating BES commands into Ant tasks Basic Syntax The options for a command-line tool translated into equivalent XML attributes. For example, the command line: iastool -verify -src cart_beans_client.jar -role DEVELOPER -warn -nostrict translates into the Ant task: For boolean-style attributes, use the base name of the attribute.
B ui ld i ng t h e e x a m p le For more information on the default values of these options, go to Chapter 29, “iastool command-line utility”. Multiple File Arguments Many commands either act on multiple files or have options which can point to multiple files. There are several ways to achieve this functionality in the equivalent Ant task. For example, the iastool -merge command: iastool -merge -target build\client.jar -type lib client\build\ local_client.jar build\local_stubs.
De p lo y i ng t h e e x a m p le 2 Set the current directory to an example directory. The "Hello World" example located at /examples/j2ee/hello is a good place to start. 3 On the command line, enter "ant". The example should build automatically. Note The server does not have to be running to build the example. However, deployment and undeployment require that the server be operational. Executing an example requires that the partion be running.
T ro u b le s h oo t i ng 2 Before calling the ant execute command, make sure that the server and the Partition are running. 3 The \examples\deploy.properties contains default settings for the Hub, Configuration, Partition, and Management Port. These default properties include: ■ hub.name=your_machine_name ■ cfg.name=j2ee ■ partition.name=standard ■ realm.name=ServerRealm ■ server.user.name=admin ■ server.user.
Chapter 29 iastool command-line utility Chapter 29 This section describes the iastool command-line utility that you can use to manage your managed objects. Important For documentation updates, go to www.borland.com/techpubs/bes. Using the iastool command-line tools The iastool utility is a set of command-line tools for manipulating managed objects. The following table shows the command-line tools provided with the iastool utility: Table 29.1 iastool command-line utilities Use... To...
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Table 29.1 iastool command-line utilities Use... To... -genclient Generate a library containing client stubs, EJB interfaces, and dependent classes. For more information, see “genclient” on page 346. -gendeployable Generate a manually deployable module. For more information, see “gendeployable” on page 347. -genstubs Generate a library containing client or server stubs only. For more information, see “genstubs” on page 348.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Table 29.1 iastool command-line utilities Use... To... -start Start a managed object. For more information, see “start” on page 365. -stop Stop a hub or managed object. For more information, see “stop” on page 366. -uncompress Uncompress a JAR file. For more information, see “uncompress” on page 368. -undeploy Remove a J2EE module from a Partition. For more information, see “undeploy” on page 369.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Option Description -package Specifies the base package name for the precompiled JSP servlet classes. The default is com.bes.compiledjsp. -loglevel <0-4> Specifies the amount of output diagnostic messages to be generated. A value greater than 2 will also leave the temporary servlet Java files for further inspection. The default is 2.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Options The following table describes the options available when using the compress tool. Option Description -src Specifies the JAR file that you want to compress. The full or relative path to the file must be specified. There is no default. -target Specifies the name of the compressed JAR file to be generated. The full or relative path to the file must be specified. There is no default.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Options The following table describes the options available when using the deploy tool. Option Description -jars Specifies the names of one or more JAR files to be deployed. To specify more than one JAR file, enter a comma (,) between each file name (no spaces). The full or relative path to the files must be specified. There is no default. -hub Specifies the name of the hub in which to deploy the JAR files.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Option Description -pwd Specifies the user's password to authenticate against the specified realm. -file Specifies a login script file containing the realm, user name , and password used to authenticate a user. The full or relative path to this file must be specified. See “Executing iastool command-line tools from a script file” on page 372 for more information.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Option Description -realm Specifies the realm used to authenticate a user when the user and password options are specified. -user Specifies the user to authenticate against the specified realm. -pwd Specifies the user's password to authenticate against the specified realm. -file Specifies a login script file containing the realm, user name , and password used to authenticate a user.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Options The following table describes the options available when using the genclient tool. Option Description -jars Specifies one or more JAR files for which you want to generate one or more client JAR files. To specify more than one JAR file, enter a comma (,) between each file name (no spaces). The full or relative path to the JAR files must be specified. There is no default.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Syntax -gendeployable -src -target [-cp ] [-args ] [-javac_args ] Default Output The default output returns nothing to standard output (stdout). Options The following table describes the options available when using the gendeployable tool. Option Description -src Specifies the JAR file that you want to use to generate a new deployable JAR file.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Default Output The default output returns nothing to standard output (stdout). Options The following table describes the options available when using the genstubs tool. Option Description -src Specifies the JAR file for which you want to generate a stubs library. The full or relative path to the JAR file must be specified. There is no default.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Syntax -info Default Output The default output is the current Java system properties for the JVM the iastool is running in. For example, the first few lines of output look like the following partial listing: application.home awt.toolkit file.encoding file.encoding.pkg file.separator java.awt.fonts java.awt.graphicsenv java.awt.printerjob java.class.path . . . : : : : : : : : : C:\Program Files\BES sun.awt.windows.WToolkit Cp1252 sun.io \ sun.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Options The following table describes the options available when using the kill tool. Option Description -hub Specifies the name of the hub on which you want to kill a managed object. -host : Specifies the host name and the listener port of the machine on which the managed object you are interested in is running.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls listpartitions Use this tool to list the partitions running on a specified hub, and optionally on a specified configuration or management port.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Option Description -pwd Specifies the user's password to authenticate against the specified realm. -file Specifies a login script file containing the realm, user name , and password used to authenticate a user. The full or relative path to this file must be specified. See “Executing iastool command-line tools from a script file” on page 372 for more information.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Option Description -realm Specifies the realm used to authenticate a user when the user and password options are specified. -user Specifies the user to authenticate against the specified realm. -pwd Specifies the user's password to authenticate against the specified realm. -file Specifies a login script file containing the realm, user name , and password used to authenticate a user.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Options The following table describes the options available when using the listservices tool. Option Description -hub Specifies the name of the hub for which you want to list the running services. -host : Specifies the host name and the listener port of the machine on which the services you are interested in are running.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Syntax -merge -jars -target -type Default Output The default output returns nothing to standard output (stdout). Options The following table describes the options available when using the merge tool. Option Description -jars Specifies the JAR files to merge, comma separated and no spaces. The full or relative path to the JAR files must be specified. There is no default.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s iastool -merge -jars proj1.jar,proj2.jar,proj2.jar -target combined.jar -type ejb2.0 migrate Use this tool to convert a JAR or XML file from J2EE version 1.2 to J2EE version 1.3. Note The migrate command only converts the deployment descriptor for an EJB; as such, code changes may also be required to implement the conversion properly in your deployment. If the conversion fails, an error is displayed.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Default Output The default output displays the patches that were applied. Options The following table describes the options available when using the patch tool. Option Description -src Specifies the JAR file to which you want to apply one or more patches. The full or relative path to the JAR file must be specified. There is no default. -patches
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Pinging Hub xyz_corp1: Running The ping tool returns one of the following states: ■ Running ■ Starting ■ Stopping ■ Not Running ■ Restarting ■ Cannot Load ■ Cannot Start ■ Terminated ■ Unknown Options The following table describes the options available when using the ping tool. Option Description -hub Specifies the hub to ping or whose services to ping. There is no default.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Option Description -pwd Specifies the user's password to authenticate against the specified realm. -file Specifies a login script file containing the realm, user name , and password used to authenticate a user. The full or relative path to this file must be specified. See “Executing iastool command-line tools from a script file” on page 372 for more information.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Options The following table describes the options available when using the pservice tool. Option Description -hub Specifies the hub where the partition service you are interested in is located. There is no default. -host : Specifies the host name and the listener port of the machine on which the partition service you are interested in is running.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls iastool -pservice -hub BES1 -cfg j2ee -partition standard -service standard_visinaming -enable -force_restart -mgmtport 24431 removestubs Use this tool to remove all stub files from a JAR file. Syntax -removestubs -jars [-targetdir ] Default Output The default output returns nothing to standard output (stdout). Options The following table describes the options available when using the removestubs tool.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Syntax -restart <-hub | -host :> [-mgmtport ] [-realm ] [-user ] [-pwd ] [-file ] or -restart <-hub | -host :> [-cfg ] -mo -moagent [-mgmtport ] [-realm ] [-user ] [-pwd ] [-file ] Default Output The default output displays the hub or managed object that
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Option Description -pwd password Specifies the user's password to authenticate against the specified realm. -file Specifies a login script file containing the realm, user name , and password used to authenticate a user. The full or relative path to this file must be specified. See “Executing iastool command-line tools from a script file” on page 372 for more information.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Options The following table describes the options available when using the setmain tool. Option Description -jar Specifies the name of the JAR or EAR file on which you want to set the main class. -uri If you are setting the main class for an EAR file, you must use the -uri option to identify the URI (Uniform Resource Identifier) path of the client JAR in the EAR.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Options The following table describes the options available when using the start tool. Option Description -hub Specifies the name of the hub on which the managed object you want to start is located. -host : Specifies the host name and the listener port of the machine on which the managed object you are interested in is running.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s Syntax -stop <-hub | -host :> [-mgmtport ] [-realm ] [-user ] [-pwd ] [-file ] or -stop <-hub | -host :> [-mgmtport ] -cfg -mo -moagent [-realm ] [-user ] [-pwd ] [-file ] Default Output The default output displays the process or processes that have bee
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Option Description -pwd Specifies the user's password to authenticate against the specified realm. -file Specifies a login script file containing the realm, user name , and password used to authenticate a user. The full or relative path to this file must be specified. See “Executing iastool command-line tools from a script file” on page 372 for more information.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s The following example uncompresses a JAR file named small.jar located in the directory c:\myprojects\ into a file named big.jar in the same location: iastool -uncompress -src c:\myprojects\small.jar -target c:\myprojects\ big.jar undeploy Use this tool to undeploy a J2EE module from a specified Partition on a specified hub and configuration.
U s in g t h e ia s t o o l c o m m a n d -l in e t o o ls Option Description -user Specifies the user to authenticate against the specified realm. -pwd Specifies the user's password to authenticate against the specified realm. -file Specifies a login script file containing the realm, user name , and password used to authenticate a user. The full or relative path to this file must be specified.
Us i n g t h e ia s t o o l c om m a nd - li ne t o ol s The verification process supports the following roles that correspond to a phase in the application's life cycle and the appropriate level of verification (similar to the J2EE role definitions): ■ Developer: This is the lowest verification level. All xml is checked for syntax as well as standard and proprietary keywords relevant to the current archive type.
E x e c u t in g ia s t o o l c o m m a n d -l in e t o o ls f r o m a s c r i pt f il e Options The following table describes the options available when using the verify tool. Option Description -src Specifies the JAR file that you want to verify. The full or relative path to the file must be specified. There is no default.
E x e c u t in g ia s t o o l c o m m a n d -l in e t o o ls f ro m a s c r i pt f i le Piping a file to the iastool utility The following example shows how to ping a hub named east1 by piping the file mylogin.txt (located in the default Borland Deployment Platform installation directory) to the iastool utility: iastool -ping -hub east1 < c:\BES\mylogin.txt where the file mylogin.
374 B E S D e ve l op e r ’s G u id e
Chapter 30 Partition XML reference Chapter 30 This section describes the XML definition of a Partition's partition.xml configuration file that contains the core meta-data for a Partition's configuration. Important For documentation updates, go to www.borland.com/techpubs/bes. element The partition element is the root node of the schema which contains the attributes and sub-elements that define the settings that control the configuration of a Borland Enterprise Server Partition.
< p ar t i t io n > el e m en t The partition element contains the following sub-elements: ■ ■ ■ ■ ■ ■ ■ ■ element The statistics.agent element configures the Partition's statistics agent. The Partition statistics agent consists of two components: ■ A statistics collector that periodically collects statistics data on the Partition and saves that data onto disk.
< p ar t i t i on > e le m e n t Attribute Description reap.older_than_secs If reap_enable is true, sets the threshold for the age (in seconds) of statistics data kept on disk before being deleted. The default is 600 seconds (10 minutes). reap.period_secs If reap_enable is true, sets the time period (in seconds) between sweeps to clean up statistics data older than reap.older_than_secs from disk. The default is 60 seconds (1 minute).
< p ar t i t io n > el e m en t Attribute Description classloader.policy Determines the type of classloader to be used by the Partition. Valid values are per_module or container. The per_module classloader policy will create a seperate application classloader for each deployed module. This policy is required if you want to be able to hot deploy. The container policy will load all deployed modules in the shared classloader. You cannot hot deploy if this policy is selected. classloader.
< p ar t i t i on > e le m e n t Attribute Description required_roles.propstorage Path to the Partition's management domain ORB required roles configuration file. runas.propstorage Path to the Partition's management domain ORB runas configuration file. All the paths are relative to the Partition's properties directory (the directory partition.xml is in). element The shutdown element determines the actions taken when a Partition stops. This empty element has no attributes.
< p ar t i t io n > el e m en t element The services element lets you configure the Partition's services. Each Partition service has a service sub-element with its specific configuration, the services element itself has the following attributes: Attribute Description autostart List of Partition's services to be started at Partition startup. The value is a space separated list of Partition service names.
< p ar t i t i on > e le m e n t Attribute Description in.management.domain Flag that indicates if the service runs in the Partition's management domain or in the Partition's user domain. startup.synchronization The type of synchronization to be performed when the service is started. Valid values are: ■ service_ready—wait for the service to be ready for up to startup.service_ready.max_wait milliseconds. ■ delay—always wait for startup.
< p ar t i t io n > el e m en t element The archives element contains configuration metadata for the archives that the Partition can host. A specific archive can have an archive sub-element with attributes specific to that archive. An archive does not have to have an archive sub-element. Attribute Description ear.repository.path Path to the Partition's EARs directory. All EARs found in that directory are loaded by the Partition on startup, unless specifically disabled with an archive element.
< p ar t i t i on > e le m e n t Attribute Description disable Flag for disabling the hosting of that archive in the Partition at startup. Valid values are true or false (default). path Path to an archive that exists outside of the Partition repositories. Use to get the Partition to host an archive from a specified path. All the paths are relative to the Partition's root directory.
384 B E S D e ve l op e r ’s G u id e
Chapter 31 Chapter 31 EJB, JSS, and JTS Properties EJB Container-level Properties Set EJB container properties in partition.xml (each Partition has its own properties file). This file is located in the following directory: /var/domains/base/configurations/configuration_name/mos/ partition_name/adm/properties Property Description Default ejb.copy_arguments=true|false This flag causes arguments to be copied in intra-bean in-process calls.
E J B Co n t a in e r -l e v el P r o pe r t ie s Property Description Default ejb.useDynamicStubs=true|false This property is only relevant for CMP 2.0 entity beans that provide local interfaces. If set, the Container, which otherwise uses CORBA to dispatch calls, uses a dynamic proxy-based scheme to dispatch calls (creating custom lightweight, nonCORBA references).
E J B Co n t a in e r- l ev e l P ro p e rt ie s Property Description Default ejb.usePKHashCodeAndEquals=tru e|false Data structures that support Active Cache (TxReady cache) and Associated Cache (Ready beans cache) use java.util.Hashtable, and java.util.HashMap. The values (entity bean instances) pooled in these data strucutres are keyed on the primary key values of the cached entity beans.
E J B Co n t a in e r -l e v el P r o pe r t ie s Property Description Default ejb.system_classpath_first=tru e|false If set to true, the custom classloader will look at the system classpath first. false ejb.sfsb.keep_alive_timeout= Defines the default value of the element used in the ejb-borland.xml descriptor. This property affects an EJB whose element is skipped or set to 0.
E J B Co n t a in e r- l ev e l P ro p e rt ie s Property Description Default ejb.logging.verbose=true|false If set to true, the EJB container logs messages about unexpected situations which potentially could require user's attention. The messages are marked with >>>> EJB LOG <<<< header. Set it to false, to suppress these messages. true ejb.logging.doFullExceptionLog ging=true|false If set, the container logs all unexpected exceptions thrown in an EJB implementation. false ejb.jss.
E J B Cu s t o m i z at io n P r op e r t ie s : D e p lo y m e nt De s c r ip t o r l ev e l Property Description Default ejb.collect.statistics=true| false Same as the ejb.collect.display_statistics property, except this property does not write the timer value to the log. false ejb.collect.display_detail_sta tistics=true|false This flag turns on the timer diagnostics, as ejb.collect.display_statistics option does. In addition, it prints out method level timing information.
E J B C u s t o m iz a t i on P r o pe r t i es : D e p lo y m e nt D e s c r ip t o r l e v el . . . 2 Property element defined on the level in the ejb-borland.xml deployment descriptor of a JAR file. This setting affects all EJBs defined in this JAR. For example, the following XML sets the ejb.maxBeansInPool property to 99 for all EJBs in the particular JAR file: . . . ejb.
C o m p le t e I n d ex o f E J B P r o pe r t i es Complete Index of EJB Properties Properties common for any kind of EJB Property Type Description Default ejb.default_transac tion_attribute Enumeration (NotSupported, Supports, Required, RequiresNew, Mandatory, Never) This property specifies a transaction attribute value for the methods which have no trans-attribute defined in the standard deployment descriptor.
C o m p le t e I nd e x o f E J B P ro p e rt ie s Property Type Description Default ejb.maxBeansInTr ansactions Integer A transaction can access any/large number of entities. This property sets an upper limit on the number of physical bean instances that EJB container will create. Irrespective of the number of database entities/rows accessed, the container will manage to complete the transaction with a smaller number of entity objects (dispatchers). The default for this is calculated as ejb.
C o m p le t e I n d ex o f E J B P r o pe r t i es Property Type Description Default ejb.findByPrimar yKeyBehavior Enumeration (Verify, Load, None) This flag indicates the desired behavior of the findByPrimaryKey method. The values are: Verify: This is the standard behavior, for findByPrimaryKey to simply verify that the specified primary key exists in the database.
C o m p le t e I nd e x o f E J B P ro p e rt ie s Message Driven Bean Properties Property Type Description Default ejb.mdb.use_jms_threads Boolean Option to switch to using the JMS providers dispatch thread rather than the Container managed thread to execute the onMessage() method. Rarely useful. false ejb.mdb.local_transaction_optimizat ion Boolean Not yet implemented false ejb.mdb.
C o m p le t e I n d ex o f E J B P r o pe r t i es Property Type Description Default ejb.mdb.rebindAttemptCount Integer This is the number of times the EJB Container attempts to re-establish a failed JMS connection or a connection that was never established for the MDB. To make the Container attempt to rebind infinitely you need to explicitly specify ejb.mdb.rebindAttemptCount= 0. 5 ejb.mdb.
C o m p le t e I nd e x o f E J B P ro p e rt ie s Property Type Description Default ejb.mdb.unDeliverableQueue String Should an MDB fail to consume a message for any reason, the message will be re-delivered by the JMS service. The message will only be redelivered five times. After five attempts, the message will be delivered to a dead queue (if one is configured). This property looks up the JNDI name of the queue. This property is used in conjunction with ejb.mdb.
C o m p le t e I n d ex o f E J B P r o pe r t i es Stateful Session Bean Properties Property Type Description Default ejb.sfsb.passivation_timeout Integer Defines the time interval (in seconds) when to passivate inactive stateful session beans into the persistent storage (JSS). 5 ejb.sfsb.instance_max Integer Defines the maximum number of instances of a particular stateful session bean allowed to exist in the EJB container memory at the same time.
S e s s io n S e rv i c e (J S S ) P ro p e rt ie s EJB Security Properties Property Type Description Default ejb.security.transportType Enumeration (CLEAR_ONLY, SECURE_ONLY, ALL) This property configures the Quality of Protection of a particular EJB. If set to CLEAR_ONLY, only nonsecure connections are accepted from the client to this EJB. This is the default setting, if the EJB does not have any method permissions.
S e s s i on S e r v ic e ( J S S ) P r o p er t i e s For example, for a Partition named "standard", by default the JSS configuration information is located in: /var/domains//configurations/ /standard/adm/properties/partition.xml For more information, go to the partition.xml reference, “ element” on page 380. Otherwise, for the location of a Partition data directory, go to the configuration.
S e s s io n S e rv i c e (J S S ) P ro p e rt ie s The JSS supports two kinds of backend storage: JDataStore or a JDBC datasource. For more information, go to Chapter 6, “Java Session Service (JSS) configuration”. Property Console Property Name Description Default jss.factoryName= Factory name Name given to the JSS factory created by this service. The service gets registered with this name in the Smart Agent (osagent).
S e s s i on S e r v ic e ( J S S ) P r o p er t i e s Property Console Property Name jss.pstore= Description Default Persistent store Specifies the JDatastore file to use for backend storage. If the file does not exist, JSS creates the file with the .jds extention, for example jss_factory.jds. For any compatible database supporting JDBC, specifies the JNDI name with the serial: prefix, for example serial:/ /datasources/OracleDB to use for backend storage.
S e s s io n S e rv i c e (J S S ) P ro p e rt ie s Property Console Property Name jss.softCommit=tru e|false jss.debug=true| false Description Default Soft commit If true, the JSS uses the JDataStore backend database with the Soft Commit mode enabled. Setting this property improves the performance of the Session Service, but can cause recently committed transactions to be rolled back after a system crash. Note: this property is applicable only if the jss.
P a r t i t io n T r a n s ac t i o n S er v i c e ( T r an s a c t io n M a n ag e r ) Partition Transaction Service (Transaction Manager) Listed below are properties that influence the behavior of the Partition Transaction Service (Transaction Manager). The properties can be specified when hosted by either a standalone EJB container or a Partition. When configuring the Partition Transaction Service for a Partition, set the properties in the partition.
P a r t i t io n T ra n s a c t io n S e r v ic e ( T r an s a c t io n M a n a ge r ) Property Description Default jts.timeout_interval= The JTS Timeout Manager examines registered transactions for timeout expiration at intervals in seconds controlled by the value of this property. Setting it to a value of 0 causes the interval to occur every 9999 seconds. 5 jts.
406 B E S D e ve l op e r ’s G u id e
Chapter 32 ejb-borland.xml Chapter 32 Important For documentation updates, go to www.borland.com/techpubs/bes.
DTD
DTD
410 B E S D e ve l op e r ’s G u id e
Chapter 33 application-client-borland.xml Chapter 33 Important For documentation updates, go to www.borland.com/techpubs/bes.
412 B E S D e ve l op e r ’s G u id e
Chapter 34 ra-borland.xml Chapter 34 Important For documentation updates, go to www.borland.com/techpubs/bes. DTD
DTD
DTD
DTD Failure to specify this value will result in VisiConnect using its defined default value. Default Value: 10 -->
DTD
DTD
DTD the name of a security role. Used in: security-map -->
420 B E S D e ve l op e r ’s G u id e
Chapter 35 jndi-definitions.xml Chapter 35 Important For documentation updates, go to www.borland.com/techpubs/bes.
422 B E S D e ve l op e r ’s G u id e
Chapter 36 web.xml Chapter 36 Important For documentation updates, go to www.borland.com/techpubs/bes.
DTD 424 B E S D e ve l op e r ’s G u id e
Index Symbols ... ellipsis 6 .httaccess files 28 | vertical bar 6 A Ant 333 building BES examples 336 customized tasks 333 deploying BES examples 337 running BES examples 337 troubleshooting BES examples 337 undeploying BES examples 337 Ant tasks and BES commands 335 ommitting attributes 335 syntax 334 usage 334 Apache httpd.
contacting 7 borland virtual directory IIS/IIOP redirector 55 Borland web container 29 adding environment variables 36 clustering 69, 73 Cocoon 99 configuration files 29 connecting to JSS 37 ENV variables 36 IIOP configuration 41 IIOP connector 41 JavaServer Pages 30 JSS and failover 72 server.
verify 370 commands conventions 6 compilejsp iastool command 341 component managed sign-on 277 compress iastool command 342 conf Apache directory 29 conf IIS directory 37 connection leak detection 285 connection management 274 connection recovery JMS 218 connector IIOP 41 Connector service 13 connectors connection management 274 container VisiConnect 287 container-managed persistence XML DTD 407 Container-Managed Persistence 2.
JMS connections 421 jndi-definitions.xml 421 resource connection factory 421 web application archive 423 web.xml 423 XML 117, 118 dump generating 345 dumpstack iastool command 345 dynamic queries EJB-QL 184 E Editions 1 EIS integration 271 EJB mapping to CORBA 110 web services 87 EJB Container ejb.classload_policy property 387 ejb.collect.display_detail_statistics property 390 ejb.collect.display_statistics property 389 ejb.collect.statistics property 390 ejb.collect.
ejb.security.trustInClient for EJB Security 399 ejb.sfsb.aggressive_passivation for EJB Container 388 ejb.sfsb.factory_name for EJB Container 388 ejb.sfsb.instance_max for Stateful Session Beans 398 ejb.sfsb.instance_max_timeout for Stateful Session Beans 398 ejb.sfsb.keep_alive_timeout for EJB Container 388 ejb.sfsb.passivation_timeout for Stateful Session Beans 398 ejb.system_classpath_first for EJB Container 388 ejb.trace_container for EJB Container 387 ejb.transactionCommitMode for Entity Beans 393 ejb.
IIOP connector 70, 71 JSS 72 web component clustering 69 fault tolerance IIOP connector 70, 71 MDB 218 web component clustering 69 -file option executing iastool from a script 372, 373 file option executing iastool from a script 373 find methods 104 G genclient iastool command 346 gendeployable iastool command 347 genstubs iastool command 348 H handle 106 Help Topics accessing 5 home interface locate 102 htdocs Apache directory 29 HTTP sessions Apache web server 74 httpd.
adding new clusters 59 adding new web applications 61 IIS redirector 36 directories 36 IIS web server connecting to web container 55 IIOP redirector 36, 55 IIOP redirector configuration 55, 59 IIOP redirector directory structure 36 versions supported 36 IIS/IIOP redirector ISAPI filter 55 virtual directory 55 info iastool command 349 internet accessing CORBA 77 ISAPI filter IIS/IIOP redirector 55 J J2EE VisiClient 115 VisiClient environment 115 J2EE APIs supported 14 J2EE connector architecture 271 JAR fil
Sonic 263 Tibco 254 JNDI serial context persistent store 225 serial context provider 224 support 109 jndi-definitions module 222 jndi-definitions.xml DTD 421 JSP definition 30 JSS 63 automatic storage 73 configuration 66 connecting to web containers 37 failover 72 JDataStore 66 JDBC datasource 66 programmatic storage 73 properties 66, 67 session management 63 storage implementation 73 web components 73 jss.debug for Java Session Service 403 jss.factoryName for Java Session Service 401 jss.
ejb.mdb.unDeliverableQueueConnectionFactor y property 396 ejb.mdb.use_jms_threads property 395 ejb.mdb.wait_timeout 395 ejb.transactionManagerInstanceName property 393, 397 Message-Driven Beans 213 client view of 214 clustering 217 connecting to JMS connection factories 215 EJB 2.
key cache size 194 named sequence table 193 process Partitions 17 process()method and ReqProcessor IDL 79 products 1 properties container-level 385 EJB 385, 392 EJB common 392 EJB customization 390 EJB security 399 ejb.classload_policy 387 ejb.collect.display_detail_statistics 390 ejb.collect.display_statistics 389 ejb.collect.statistics 390 ejb.collect.stats_gather_frequency 389 ejb.copy_arguments 385 ejb.default_transaction_attribute 392 ejb.findByPrimaryKeyBehavior 394 ejb.finder.
obtain reference to 103 removestubs iastool command 362 ReqProcessor IDL 78 process()method 79 ReqProcessor Interface Definition Language (IDL) 77 resource adapters 285 VisiConnect 287 resource references DTD 407 res-ref-name 117 res-ref-names 119 restart iastool command 362 S script file -file option 373 passing a file to iastool 373 piping a file to iastool 373 running iastool utilities from 372 Security ejb.security.transportType property 399 ejb.security.
T table properties optimisticConcurrencyBehavior 175 XML representation DTD 407 Technical Support contacting 7 thread dump generating 345 Tibco clustered service 260 runtime pluggability 254 Tibco Admin Console 256 Tomcat web container Cocoon 99 Tomcat-based web container 29 adding environment variables 36 configuration files 29 connecting to JSS 37 ENV variables 36 IIOP configuration 41 IIOP connector 41 JavaServer Pages 30 server.
component managed sign-on 277 connection management 274 description 281 managed sign-on 277 overview 287 ra managed sign-on 277 security 276 VisiConnect container overview 287 partition service 289 standalone process 289 W WAR file 29, 30, 31 containing web services 93 web services 93, 94 WEB-INF directory 31 WAR files precompiling Java Server Pages 341 web application WAR file 31 WEB-INF directory 31 web application archive DTD 423 Web application archive (WAR) file 31 Web Application Archive File (WAR fi
X XML DTD 117, 118 VisiClient 116 grammar 117 web application DTD 423 Web services 92 web services 85, 88 xml Cocoon 99 438 B E S D e ve l op e r ’s G u id e
