User's Guide - Borland Technical Publications

User’s GuideVERSION 5.2Borland ®Enterprise ServerBorland Software Corporation100 Enterprise Way, Scotts Valley, CA 95066-3249www.borland.com

Borland Software Corporation may have patents and/or pending patent applications covering subject matter in thisdocument. Please refer to the product CD or the About dialog box for the list of applicable patents.The furnishing ofthis document does not give you any license to these patents.COPYRIGHT © 1992–2002 Borland Software Corporation. All rights reserved. All Borland brand and product namesare trademarks or registered trademarks of Borland Software Corporation in the United States and other countries.All other marks are the property of their respective owners.This product includes software developed by the Apache Software Foundation (http://www.apache.org/).BES0052WW210030102030405-9 8 7 6 5 4 3 2 1PDF

RMI-IIOP . . . . . . . . . . . . . . . . . . 3-11Other Technologies . . . . . . . . . . . . . 3-11Shared Services . . . . . . . . . . . . . . . . . 3-112PC Transaction Service . . . . . . . . . . 3-12Apache 2.0 Web Server . . . . . . . . . . . 3-12Smart Agent . . . . . . . . . . . . . . . . . 3-12SonicMQ Daemon . . . . . . . . . . . . . 3-13Viewing log files . . . . . . . . . . . . . . . . . . 3-13Server properties . . . . . . . . . . . . . . . . . . 3-14Server General tab . . . . . . . . . . . . . . .3-14Server Properties tab . . . . . . . . . . . . . . 3-14Server License tab . . . . . . . . . . . . . . . 3-15Partition properties . . . . . . . . . . . . . . . . 3-15Partition General tab . . . . . . . . . . . . . . 3-16Partition properties . . . . . . . . . . . . . 3-16Security Settings . . . . . . . . . . . . . . 3-16Partition Properties tab . . . . . . . . . . . .3-16Virtual Machine . . . . . . . . . . . . . . . 3-16Server Connection Manager Settings . . .3-17Class Loading tab . . . . . . . . . . . . . . . 3-17Monitoring tab . . . . . . . . . . . . . . . . . 3-17Deployed modules. . . . . . . . . . . . . . . . . 3-18Viewing archive attributes . . . . . . . . . .3-18About Enterprise Archives (EARs) . . . . . . 3-20Viewing EARs . . . . . . . . . . . . . . . . 3-20Removing modules from a container . . . . 3-21About web archives . . . . . . . . . . . . . . 3-21Viewing WARs . . . . . . . . . . . . . . . 3-21About the libraries . . . . . . . . . . . . . . .3-22Viewing libraries . . . . . . . . . . . . . . 3-22Viewing library attributes . . . . . . . . . 3-22About resource adapters. . . . . . . . . . . . 3-22Viewing resource adapters. . . . . . . . . 3-23Viewing Resource Adapterinformation . . . . . . . . . . . . . . . . 3-23Viewing JAR information . . . . . . . . . . . 3-23Viewing Jars . . . . . . . . . . . . . . . . . 3-23Viewing EJB information . . . . . . . . . . .3-24Enterprise bean types . . . . . . . . . . . . . 3-25About EJB Containers . . . . . . . . . . . . . 3-26Persistence support . . . . . . . . . . . . . 3-26Viewing EJB container services attributes . .3-27About web containers . . . . . . . . . . . . . 3-28Viewing the Web container . . . . . . . . 3-28Partition Services. . . . . . . . . . . . . . . . . . 3-28EJB Container properties . . . . . . . . . . .3-28EJB Statistics tab. . . . . . . . . . . . . . . 3-29Bean States tab . . . . . . . . . . . . . . . 3-31JDataStore properties . . . . . . . . . . . . . 3-32Naming Service properties . . . . . . . . . . 3-32Session Service properties . . . . . . . . . . 3-33Transaction Service properties . . . . . . . . 3-33VisiConnect Service properties. . . . . . . . 3-34Factory States tab . . . . . . . . . . . . . 3-34Web Container properties . . . . . . . . . . 3-35Web Container Server Statistics tab . . . 3-35Configuring Web Containerproperties . . . . . . . . . . . . . . . . . 3-36Shared Services properties . . . . . . . . . . . . 3-392PC Transaction Service properties . . . . . 3-40Apache properties . . . . . . . . . . . . . . . 3-41Smart Agent properties . . . . . . . . . . . . 3-41SonicMQ Broker properties . . . . . . . . . 3-41Chapter 4The Installations view 4-1Context menu commands in theInstallations view . . . . . . . . . . . . . . . . . 4-2Editing files in the Installations view . . . . . . . 4-2Chapter 5The Clusters View 5-1What is the Borland Management Service? . . . 5-1The Management Agent . . . . . . . . . . . . 5-2The Management Hub . . . . . . . . . . . . . 5-2Using the Clusters View . . . . . . . . . . . . . . 5-3Creating a Managed Apache Web Server . . . 5-3Creating a Managed JDataStore Database . . 5-5Creating a Managed SonicMQ MessagingService . . . . . . . . . . . . . . . . . . . . . 5-6Creating Clusters . . . . . . . . . . . . . . . . . . 5-7Creating a Cluster Definition with theCluster Wizard . . . . . . . . . . . . . . . . . 5-7Step One . . . . . . . . . . . . . . . . . . . 5-8Step Two . . . . . . . . . . . . . . . . . . . 5-9Step Three . . . . . . . . . . . . . . . . . 5-10Step Four . . . . . . . . . . . . . . . . . . 5-11Step Five . . . . . . . . . . . . . . . . . . 5-12Step Six . . . . . . . . . . . . . . . . . . . 5-13Editing an existing Cluster Definition . . 5-14The Cluster in Action: Using the AddServer Wizard . . . . . . . . . . . . . . . . 5-14Viewing Cluster Information. . . . . . . . . 5-15Understanding the State Icons . . . . . . . . 5-17Start/Stop Dependencies in BorlandEnterprise Server . . . . . . . . . . . . . . . . 5-19Starting Managed Objects . . . . . . . . . . 5-21Stopping Managed Objects. . . . . . . . . . 5-22ii

Chapter 6Configuring security with the BorlandManagement Console 6-1Getting Started . . . . . . . . . . . . . . . . . . . 6-1Setting the logging level. . . . . . . . . . . . . . 6-2Configuring Authentication . . . . . . . . . . . 6-2Configuring Authorization . . . . . . . . . . . . 6-3Creating a new authorization rolemapfile . . . . . . . . . . . . . . . . . . . . . . . 6-4Cloning an authorization rolemap file . . . . 6-4Creating a new authorization role . . . . . . 6-5Creating an authorization rule . . . . . . . . 6-5Editing an authorization rule . . . . . . . . . 6-6Creating an authorization role reference. . . 6-6Advanced Security Configuration . . . . . . . . 6-6Chapter 7Wizards 7-1Using the Borland Enterprise Serverwizards . . . . . . . . . . . . . . . . . . . . . . 7-1Additional wizards. . . . . . . . . . . . . . . 7-2Deploying J2EE components . . . . . . . . . . . 7-2The deployment process . . . . . . . . . . . . . 7-3Deployment Wizard . . . . . . . . . . . . . . . . 7-3Merge Wizard . . . . . . . . . . . . . . . . . . . 7-6Verify Wizard. . . . . . . . . . . . . . . . . . . . 7-9XML Migration Wizard . . . . . . . . . . . . . .7-10Stub Generation Wizard. . . . . . . . . . . . . . 7-12Creating client stubs for non-containerapplications . . . . . . . . . . . . . . . . . . 7-12Creating a 'stubs only' library file . . . . . . 7-14Creating a JAR suitable for manualdeployment . . . . . . . . . . . . . . . . . . 7-15Remove Stubs Wizard . . . . . . . . . . . . . . . 7-16Apply Patch Wizard . . . . . . . . . . . . . . . . 7-17JAR Wizard . . . . . . . . . . . . . . . . . . . . . 7-17Registration Wizard . . . . . . . . . . . . . . . .7-17Export EJB as a Web Service Wizard . . . . . . .7-18Chapter 8Using the Application Assembly Tool 8-1Starting the Application Assembly tool . . . . . 8-2Opening an archive . . . . . . . . . . . . . . . . 8-3Performing actions on an archive . . . . . . . . 8-3Adding files to an archive . . . . . . . . . . . 8-3Editing text files in archives . . . . . . . . . . 8-4Removing files from an archive. . . . . . . . 8-5Saving an archive . . . . . . . . . . . . . . . . . 8-5Editing archive files. . . . . . . . . . . . . . . . . 8-5Creating archives . . . . . . . . . . . . . . . . . . 8-6Extracting modules . . . . . . . . . . . . . . . . . 8-7Verifying archives . . . . . . . . . . . . . . . . . . 8-8Supported archive types . . . . . . . . . . . . 8-8Chapter 9Using the Deployment DescriptorEditor 9-1Archive directory structures . . . . . . . . . . . . 9-2About the descriptor . . . . . . . . . . . . . . . . 9-2Usage conditions . . . . . . . . . . . . . . . . . . 9-2General . . . . . . . . . . . . . . . . . . . . . . 9-2EARs . . . . . . . . . . . . . . . . . . . . . . . 9-3WARs . . . . . . . . . . . . . . . . . . . . . . . 9-3WAR directory structures. . . . . . . . . . . . 9-3EJBs . . . . . . . . . . . . . . . . . . . . . . . . 9-4JNDI Definitions. . . . . . . . . . . . . . . . . 9-4Starting the editor. . . . . . . . . . . . . . . . . . 9-5Adding descriptors . . . . . . . . . . . . . . . . . 9-5The types of information in thedescriptor. . . . . . . . . . . . . . . . . . . . 9-6Enterprise bean structural information . . . . 9-6Enterprise bean application assemblyinformation. . . . . . . . . . . . . . . . . . . 9-7Creating Deployment Descriptors. . . . . . . 9-7Creating a JNDI definition descriptor. . . . . 9-8JNDI definitions and datasource archives(DARs) . . . . . . . . . . . . . . . . . . . . . 9-9Creating a JNDI definitions archive(DAR) . . . . . . . . . . . . . . . . . . . . . . 9-9Setting properties for datasources . . . . . . 9-10Adding EAR archives . . . . . . . . . . . . . . 9-12EAR properties . . . . . . . . . . . . . . . . 9-12Adding WAR information . . . . . . . . . . . . 9-13WAR properties . . . . . . . . . . . . . . . . 9-14EJB JAR properties . . . . . . . . . . . . . . 9-21Application Client JAR properties. . . . . . 9-22Adding or changing bean information . . . . . 9-23Setting classpath information . . . . . . . . 9-24Changing bean information . . . . . . . . . 9-24Enterprise bean information . . . . . . . . . . . 9-25Environment panel . . . . . . . . . . . . . . 9-26EJB References panel . . . . . . . . . . . . . 9-27Security Identity panel . . . . . . . . . . . . 9-27Security Role References panel . . . . . . . 9-29Message-Driven Bean Panel . . . . . . . . . 9-32Container transactions . . . . . . . . . . . . . . 9-33Adding a container transaction . . . . . . . 9-33iii

Adding security roles and methodpermissions . . . . . . . . . . . . . . . . . . . .9-35About Security Roles. . . . . . . . . . . . . . 9-35Creating a security role . . . . . . . . . . . .9-36Assigning method permissions . . . . . . . . . 9-37Adding CMP 1.1 information. . . . . . . . . . . 9-39Finders panel . . . . . . . . . . . . . . . . . . 9-40Adding CMP 2.0 information. . . . . . . . . . . 9-41Adding a new datasource. . . . . . . . . . . . . 9-41Isolation levels . . . . . . . . . . . . . . . . . 9-42The EJB Designer. . . . . . . . . . . . . . . . . . 9-42EJB Designer and CMP 2.0 generalinformation . . . . . . . . . . . . . . . . . . 9-43Editing entity CMP properties . . . . . . . . 9-44Finder methods in the EJB Designer . . . . . 9-44Table Reference Editor . . . . . . . . . . . . . 9-45Borland-specific deployment descriptors . . . .9-47The Borland DTDs . . . . . . . . . . . . . . .9-48Chapter 10iastool command-line utility 10-1Using the iastool command-line tools . . . . . . 10-1compilejsp . . . . . . . . . . . . . . . . . . . .10-2compress . . . . . . . . . . . . . . . . . . . . 10-3deploy . . . . . . . . . . . . . . . . . . . . . . 10-4dumpstack . . . . . . . . . . . . . . . . . . . 10-7genclient . . . . . . . . . . . . . . . . . . . . . 10-8gendeployable . . . . . . . . . . . . . . . . . 10-9genstubs . . . . . . . . . . . . . . . . . . . . 10-10iaschangeowner (UNIX only) . . . . . . . . 10-11Changing ownership of a serverinstance. . . . . . . . . . . . . . . . . . 10-11info . . . . . . . . . . . . . . . . . . . . . . . 10-13kill . . . . . . . . . . . . . . . . . . . . . . . 10-13listpartitions. . . . . . . . . . . . . . . . . . 10-15listservers . . . . . . . . . . . . . . . . . . . 10-16listservices. . . . . . . . . . . . . . . . . . . 10-17merge . . . . . . . . . . . . . . . . . . . . . 10-18migrate . . . . . . . . . . . . . . . . . . . . 10-19patch . . . . . . . . . . . . . . . . . . . . . . 10-19ping . . . . . . . . . . . . . . . . . . . . . . 10-20removestubs . . . . . . . . . . . . . . . . . 10-22restart . . . . . . . . . . . . . . . . . . . . . 10-22setmain . . . . . . . . . . . . . . . . . . . . 10-24start . . . . . . . . . . . . . . . . . . . . . . 10-24stop. . . . . . . . . . . . . . . . . . . . . . . 10-26uncompress . . . . . . . . . . . . . . . . . . 10-27undeploy . . . . . . . . . . . . . . . . . . . 10-28usage. . . . . . . . . . . . . . . . . . . . . . 10-29verify . . . . . . . . . . . . . . . . . . . . . 10-30Executing iastool command-line tools froma script file . . . . . . . . . . . . . . . . . . . 10-31Piping a file to the iastool utility. . . . . . 10-31Passing a file to the iastool utility . . . . . 10-32Chapter 11Dreamweaver UltraDev Plug-in 11-1Installing the Dreamweaver UltraDevPlug-in . . . . . . . . . . . . . . . . . . . . . . 11-1Configuring Dreamweaver to use the JSPExtension. . . . . . . . . . . . . . . . . . . . . 11-2Inserting JSP tags into your Java Server Page . 11-4HTML comments . . . . . . . . . . . . . . . . . 11-4JSP declarations . . . . . . . . . . . . . . . . . . 11-5JSP expressions . . . . . . . . . . . . . . . . . . 11-6JSP forward actions . . . . . . . . . . . . . . . . 11-7JSP getProperty actions. . . . . . . . . . . . . . 11-8JSP hidden comments . . . . . . . . . . . . . . 11-9JSP include actions . . . . . . . . . . . . . . . . 11-9JSP include directives. . . . . . . . . . . . . . .11-11JSP page directives . . . . . . . . . . . . . . . .11-11JSP Plug-in actions . . . . . . . . . . . . . . . .11-13JSP scriptlets . . . . . . . . . . . . . . . . . . . .11-15JSP setProperty actions . . . . . . . . . . . . . .11-15JSP taglib directives . . . . . . . . . . . . . . . .11-16JSP useBean actions . . . . . . . . . . . . . . . .11-17Index 1-1iv

Figures2.1 Management Console login screen withdefault login settings . . . . . . . . . . . . 2-22.2 Local Address File tab. . . . . . . . . . . . 2-162.3 Address File tab . . . . . . . . . . . . . . .2-173.1 EAR attributes Details tab . . . . . . . . . 3-213.2 Viewing JAR XML . . . . . . . . . . . . . . 3-243.3 Bean statistic properties - editingpreferences . . . . . . . . . . . . . . . . . . 3-253.4 Container services' attributes - namingservice. . . . . . . . . . . . . . . . . . . . . 3-275.1 Management Agent port. . . . . . . . . . . 5-25.2 Top-level nodes. . . . . . . . . . . . . . . . 5-35.3 Apache Wizard. . . . . . . . . . . . . . . . 5-45.4 New Apache instance . . . . . . . . . . . . 5-45.5 Viewing Apache information. . . . . . . . 5-55.6 JDataStore Wizard . . . . . . . . . . . . . . 5-55.7 New JDataStore process. . . . . . . . . . . 5-65.8 Viewing JDataStore information . . . . . . 5-65.9 SonicMQ Wizard. . . . . . . . . . . . . . . 5-75.10 Cluster Wizard step 1 . . . . . . . . . . . . 5-85.11 Cluster Wizard step 2 . . . . . . . . . . . . 5-95.12 Cluster Wizard step 3 . . . . . . . . . . . . 5-105.13 Cluster Wizard step 4 . . . . . . . . . . . . 5-115.14 Cluster Wizard step 5 . . . . . . . . . . . . 5-125.15 Cluster Wizard step 6 . . . . . . . . . . . . 5-135.16 A new cluster. . . . . . . . . . . . . . . . . 5-145.17 Add Server Wizard . . . . . . . . . . . . . 5-155.18 Deployed cluster tree representation . . .5-165.19 Deployed cluster graphicalrepresentation . . . . . . . . . . . . . . . . 5-175.20 Selecting desired state for an object . . . .5-185.21 State icons legend . . . . . . . . . . . . . .5-195.22 Example Clusters View tree representation. .5-205.23 Starting and stopping of components byother components . . . . . . . . . . . . . .5-215.24 Starting managed objects . . . . . . . . . . 5-225.25 Stopping managed objects . . . . . . . . . 5-226.1 Configure Partitions Security tab . . . . . 6-26.2 Security Domain Browser. . . . . . . . . . 6-46.3 Rolemap Rule editor. . . . . . . . . . . . . 6-56.4 Configure Partitions VisiBroker tab . . . . 6-77.1 Deployment Wizard: Step 1 . . . . . . . . 7-47.2 Advanced Deployment Options StubGeneration tab . . . . . . . . . . . . . . . . 7-57.3 Advanced Deployment Options Verifytab . . . . . . . . . . . . . . . . . . . . . . . 7-57.4 Deployment Wizard: Step 2 . . . . . . . . . 7-67.5 Merge Wizard . . . . . . . . . . . . . . . . . 7-77.6 Merge Wizard module selection . . . . . . 7-87.7 Merge Wizard Output Location . . . . . . . 7-87.8 Verify Wizard . . . . . . . . . . . . . . . . . 7-97.9 XML Migration Wizard . . . . . . . . . . 7-117.10 XML Migration Wizard Results . . . . . . 7-117.11 Stub Generation Wizard: Step 1 . . . . . . 7-127.12 Stub Generation Wizard: Step 2 . . . . . . 7-137.13 Stub Generation Wizard: Step 3 (forclient stubs) . . . . . . . . . . . . . . . . . 7-137.14 Class Path Editor . . . . . . . . . . . . . . 7-147.15 Stub Generation Wizard: Step 3 (for a . . . . .stubs only file). . . . . . . . . . . . . . . . 7-157.16 Stub Generation Wizard: Step 3 (for adeployable JAR file) . . . . . . . . . . . . 7-167.17 Starting the Export EJB as a Web ServiceWizard . . . . . . . . . . . . . . . . . . . . 7-187.18 Export EJB as a Web Service Wizard:Step 1 . . . . . . . . . . . . . . . . . . . . . 7-197.19 Export EJB as a Web Service Wizard:Step 2 . . . . . . . . . . . . . . . . . . . . . 7-197.20 Export EJB as a Web Service Wizard:Step 3 . . . . . . . . . . . . . . . . . . . . . 7-207.21 Export EJB as a Web Service Wizard:Step 4 . . . . . . . . . . . . . . . . . . . . . 7-208.1 The Application Assembly Tool. . . . . . . 8-28.2 An open archive file . . . . . . . . . . . . . 8-38.3 Adding files to an archive . . . . . . . . . . 8-48.4 Editing a file in an archive . . . . . . . . . . 8-58.5 New Module Wizard . . . . . . . . . . . . . 8-68.6 Creating an archive file . . . . . . . . . . . 8-78.7 Extract Modules window . . . . . . . . . . 8-78.8 Verify Module window . . . . . . . . . . . 8-89.1 The Object Gallery . . . . . . . . . . . . . . 9-89.2 Adding an environment property . . . . 9-159.3 Setting login and error pages forForm-based authentication . . . . . . . . 9-189.4 The Classpath Editor . . . . . . . . . . . . 9-249.5 Security Identity Panel . . . . . . . . . . . 9-299.6 Security role references panel . . . . . . . 9-309.7 Message-Driven Bean panel . . . . . . . . 9-339.8 New container transaction. . . . . . . . . 9-349.9 Security roles properties panel . . . . . . 9-37vi

9.10 Specifying Method Permissions . . . . . . 9-399.11 CMP 1.1 fields . . . . . . . . . . . . . . . .9-399.12 Editing finder methods . . . . . . . . . . . 9-459.13 Specifying table references . . . . . . . . . 9-469.14 Using a cross table for many-to-manyrelationships . . . . . . . . . . . . . . . . . 9-4711.1 Macromedia Extension Manager. . . . . . 11-211.2 Preferences dialog box . . . . . . . . . . . 11-311.3 Borland JSP Extension Configurationdialog box . . . . . . . . . . . . . . . . . . 11-311.4 HTML Comment dialog box . . . . . . . . 11-511.5 JSP Declaration dialog box . . . . . . . . . 11-611.6 JSP Expression dialog box . . . . . . . . . 11-711.7 Forward Action dialog box . . . . . . . . . 11-711.8 Parameters dialog box. . . . . . . . . . . . 11-811.9 getProperty Action dialog box . . . . . . . 11-811.10 Hidden Comment dialog box . . . . . . . 11-911.11 JSP Include Action dialog box . . . . . . 11-1011.12 Parameters dialog box. . . . . . . . . . . 11-1011.13 JSP Include Directive dialog box . . . . . 11-1111.14 JSP Page Directive dialog box . . . . . . 11-1211.15 JSP Plugin Action dialog box . . . . . . . 11-1311.16 Parameters dialog box. . . . . . . . . . . 11-1411.17 JSP Scriptlet dialog box . . . . . . . . . . 11-1511.18 JSP setProperty Action dialog box . . . . 11-1611.19 Taglib Directive dialog box . . . . . . . . 11-1711.20 JSP useBean Action dialog box . . . . . . 11-17vii

viii

Chapter1Chapter1Introduction to Borland EnterpriseServerThe Borland Enterprise Server is a set of services and tools that enable you to build,deploy, and manage enterprise applications in your corporate environment. Theseapplications provide dynamic content by using JSP, servlets, and Enterprise JavaBean (EJB) technologies.Borland Enterprise Server DocumentationImportantThe Borland Enterprise Server documentation set includes the following:• The Borland Enterprise Server Installation Guide• The Borland Enterprise Server User’s Guide• The Borland Enterprise Server Developer’s Guide• The Borland Enterprise Server VisiBroker Developer’s Guide• The Borland Enterprise Server VisiBroker VisiNotify Guide• The Borland Enterprise Server VisiBroker Programmer’s Reference• The Borland Enterprise Server VisiBroker GateKeeper Guide• The Borland Enterprise Server Pet Store TutorialThe documentation in PDF format and updates to the product documentation areavailable on the web at http://www.borland.com/techpubs/bes.Introduction to Borland Enterprise Server 1-1

Borland Enterprise Server DocumentationNoteWindowsUNIXNoteTo access the standalone online Help Topics on a machine where the product isinstalled, use one of the following methods:• Choose Start|Programs|Borland Enterprise Server|Help Topics• Open a command shell and enter the command:beshelpTo recognize the beshelp command, your path system variable must include the/bin directory, or you can enter the path explicitly.To access the online Help Topics and the Pet Store Tutorial on a machine where theproduct is installed, use one of the following methods:• From within the Management Console, choose|Help• (Help Topics only) From within the DDEditor, choose|Help• (Help Topics only) (VisiBroker standalone) From within the VisiBroker Console,choose|HelpThe Installation Guide describes how to install the Borland Enterprise Server on yournetwork. It is written for system administrators who are familiar with Windows NT,2000, or UNIX operating systems.The User's Guide provides information about using the Borland Enterprise Server.This information includes how to use the graphical interface tools to start, stop, andmanage servers and services, how to use EJB and web containers, the wizards, theDeployment Descriptor Editor, and the Application Assembly Tool. This guide alsodescribes the Dreamweaver UtraDev plug-in.The Developer's Guide provides detailed information about packaging, deployment,and management of distributed object-based applications in their operationalenvironment. Tuning services, establishing connections, and advanced approaches tocommon problems are discussed. Additionally, this guide describes the VisiClientContainer.The VisiBroker Developer's Guide describes how to develop VisiBroker applications inJava or C++. It familiarizes you with configuration and management of theVisibroker ORB using its consoles and properties file. Also described is the IDLcompiler, the Smart Agent, the Location, Naming and Event Services, the objectActiActivationmon, the Quality of Service, and the Interface Repository.The VisiBroker VisiNotify Guide describes Borland's implementation of the OMGstandard, Notification Service. This guide discusses how to use the major features ofthe notification messaging framework, in particular, the Quality of Service (QoS)properties, Filtering, and Publish/Subscribe Adapter (PSA).The VisiBroker Programmer's Reference provides a description of the classes andinterfaces supplied with VisiBroker for Java and C++ in addition to informationabout how to use the programming tools and command-line options.The VisiBroker GateKeeper Guide describes how to use the VisiBroker GateKeeper toenable VisiBroker clients to communicate with servers across networks, while stillconforming to the security restrictions imposed by web browsers and firewalls.1-2 User’ s Guide

Documentation conventionsThe Borland Enterprise Pet Store Tutorial guides you through a basic tour of the BESproduct with particular focus on clustering using the Borland Management Server (abuilt-in management service).Documentation conventionsThe documentation for the Borland Enterprise Server uses the typefaces and symbolsdescribed below to indicate special text:Conventionitalicscomputerbold computerPlatform conventionsThe Borland Enterprise Server documentation uses the following symbols to indicateplatform-specific information:Windows: Windows NT and Windows 2000WinNT: Windows NT onlyWin2000: Windows 2000 onlyUNIX: UNIX platformsSolaris: Solaris onlyLinux: Linux onlyContacting Borland supportUsed forInformation that the user or applicationprovides, such as variables in syntax diagrams.It is also used for new terms and book titles.Sample command lines and code.In text, bold indicates information the usertypes in. In code samples, bold highlightsimportant statements.[ ] Optional items.... Previous argument that can be repeated.| Two mutually exclusive choices.KeycapsA key on your keyboard. For example, PressEsc to exit.Borland offers a variety of support options. These include free services on theInternet where you can search our extensive information base and connect with otherusers of Borland products. In addition, you can choose from several categories oftelephone support, ranging from support on installation of Borland products to feebased,consultant-level support and detailed assistance.Introduction to Borland Enterprise Server 1-3

Contacting Borland supportFor more information about Borland's support services, please see our web site at:http://www.borland.com/devsupportand select your geographic region.For Borland support worldwide information, visit:http://www.borland.com/devsupport/contacts.When contacting Borland's support, be prepared to provide the followinginformation:• Name• Company and site ID• Phone number• Your Access ID number (U.S.A. only• Operating system and version (for example, Windows NT Server 4.0 with ServicePack 5)• Borland product name and version (for example, Borland Enterprise Server 5.2,AppServer Edition)• Any patches or service packs applied• Client language and version (if applicable)• Database and version (if applicable)• Detailed description and history of the problem• Any log files which indicate the problem• Details of any error messages or exceptions raisedOnline resourcesYou can get information from any of these online sources:World Wide WebOnline SupportListservhttp://www.borland.comhttp://support.borland.com (access ID required)To subscribe to electronic newsletters, use the online format:http://www.borland.com/contact/listserv.htmlor, for Borland's international listserver,http://www.borland.com/contact/intlist.html1-4 User’ s Guide

Contacting Borland supportWorld Wide WebCheck http://www.borland.com regularly. The Borland Enterprise Server ProductTeam posts white papers, competitive analyses, answers to FAQs, sampleapplications, updated software, updated documentation, and information about newand existing products.You may want to check these URLs in particular:• http://www.borland.com/products/downloads (updated software and otherfiles)• http://www.borland.com/techpubs/bes (documentation)• http://community.borland.com (contains our web-based news magazine fordevelopers)Borland newsgroupsNoteYou can participate in many threaded discussion groups devoted to the BorlandEnterprise Server products.You can find user-supported newsgroups for Enterprise Server and other Borlandproducts at:http://www.borland.com/newsgroups.These newsgroups are maintained by users and are not official Borland sites.Introduction to Borland Enterprise Server 1-5

1-6 User’ s Guide

Chapter2Chapter2Using theBorland ManagementConsoleImportantBorland Enterprise Server provides a graphical user interface, the BorlandManagement Console which functions as the main control point for the server. TheConsole lets you view servers on the network, start and stop servers and services,change server configurations, and manage the services and tools that enable yourenterprise to build, deploy, and manage component-based enterprise applications.The Console also enables you to view deployed modules, set deployment properties,and monitor performance. The Borland Enterprise Server typically runs on a largeshared UNIX or Windows NT machine, while the Console runs on any machine fromwhich users want to view or modify the distributed system. Once the Console isinstalled, you can use it to deploy to any Borland Enterprise Server instance on yournetwork.This section provides an overview of how to use the Console to start and stop aserver, change server configurations, and manage top-level services.The left most area of the Console window lets you select from the following views:• The Clusters View – see Chapter 5, “The Clusters View”• The Servers View – see Chapter 3, “The Servers view”• The Installations View – see Chapter 4, “The Installations view”• VisiBroker Console – see the VisiBroker Developer's GuideFor documentation updates, go to www.borland.com/techpubs/bes.Using the Borland Management Console 2-1

Starting and logging onto the Borland Management ConsoleStarting and logging onto the Borland Management ConsoleNoteTo start the Management Console, use one of the following methods:1 Windows: Double-click the Borland Enterprise Server Management Console iconon your desktop, or choose Start|Programs|Borland Enterprise Server|Management Console.UNIX: Open a command shell and enter the following command:consoleTo recognize the console command, your path system variable must include the bindirectory (install_dir/bin), or you can enter the path explicitly.The Borland Management Console login screen appears.Figure 2.1 Management Console login screen with default login settingsNote2 Enter your user name, password, and Server Realm.To use the Borland default login settings, enter the password: admin.3 Click Login.The Borland Management Console appears.Licensing and registering the serverThis following sections describe how to license and register your server using theConsole.Licensing the serverNoteYou can license the Borland Enterprise Server during installation. If you do not enterlicense information during installation you are required to enter it using the Console.To enter license information:2-2 User’ s Guide

Licensing and registering the server1 In the navigation pane of the Console, expand Enterprise Servers.2 Right-click the server that you want to license and select Update License.3 Enter your serial number and key.Registering the serverThe product registration wizard allows you to register electronically or by telephone.Electronic registration is recommended if you have an Internet connection. You mustregister the Borland Enterprise Server to comply with the license agreement.NoteRegister by phone1 To register your server by phone, right-click the server that you want to register inthe navigation pane and select Register Server.2 Select the “I do not have an Internet connection” radio button.3 Select your geographic location from the ”Telephone Number” drop-down menu.4 Call the telephone number shown for your geographic location to speak to aBorland representative. Leave the screen up while you talk to the Borlandrepresentative.If your serial number and authorization key are not already showing on thescreen, you must go back and update your Borland Enterprise Server licenseinformation using the Console.5 Enter the Activation Key the Borland representative gives you in the ActivationKey field.6 Complete your registration by following the Registration wizard's instructions.Register onlineIf you are a Borland Community Member and/or have a Software RegistrationAccount from a previous electronic product registration, you can take advantage ofthe ”Quick Registration” option.If you are not a Member and do not have an Account, you must create a newSoftware Registration Account in order to register your server. You can use your newSoftware Registration Account to quickly register other Borland products.Quick RegistrationTo take advantage of Quick Registration you must provide your Borland CommunityMember user name (or email address) along with your Community password. If youare not a Member you can alternatively use your Software Registration Account username and password.To use Quick Registration:1 Right-click the server that you want to register in the navigation pane and selectRegister Server.Using the Borland Management Console 2-3

Console main menuNoteNote2 Select either the ”I am a Borland Community Member” or ”I am not a Member, butI have a Software Registration Account” radio button. Click Next.To become a Borland Community Member (Borland Developer Network) go tohttp://community.borland.com.3 Enter your Borland Community Member user name (or email address) along withyour Community password. Alternatively you may use your SoftwareRegistration Account user name and password. Click Next.If you have forgotten your Community Member password you may obtain it fromthe Community web site at http://community.borland.com.4 If you use a proxy to connect to the Internet, enter the host and port. If your proxyrequires authentication, enter the user name and password. Click next.Your registration is now processing. If there is an error, such as an invalid username or password, click the Back button to change information or click Next forother registration options.Console main menuThe Console provides the following main menu items:• Console – see “Console menu” on page 2-4• View – see “View menu” on page 2-5• Wizards – see “Wizards menu” on page 2-5• Tools – see “Tools menu” on page 2-5• Help – see “Help menu” on page 2-6Console menuThe following table describes the commands on the Console menu.Table 2.1Select...RefreshPreferences...LoginLogoutExitConsole menu commandsTo...manually update server state information shown in the Console.open the Preferences dialog box to set Console and Server configurationssettings. See “Setting Console preferences” on page 2-7.log on to the console with your user name, password, and realm credentials.log out of the console so that you can log on with new user name, password,and realm credentials.dismiss the Console.2-4 User’ s Guide

Console main menuView menuThe following table describes the commands on the View menu.Table 2.2Select...MessagesTool barStatus barView menu commandsTo...show or hide the errors window.show or hide the tool bar at the top of the Console window.show or hide the status bar at the bottom of the Consolewindow.Wizards menuThe following table describes the commands on the Wizards menu.Table 2.3Select...Deployment WizardCluster WizardMerge WizardVerify WizardTools menuWizards menu commandsXML Migration WizardStub Generation WizardStub Removal WizardApply Patch WizardJar WizardTo start a wizard...that helps you deploy on or more J2EE modules.that helps you create a cluster.that helps you merge multiple J2EE modules into a singlemodule.that helps you check an archive file for correctness andconsistency, and to check if all the elements required fordeploying your application are in place.that converts a J2EE version 1.2 module to version 1.3, or toconvert a J2EE version 1.3 module to version 1.2.to generate stub classes that can be stored in various archivetypes.to remove stub classes an archive.to apply one or more patches to an archive.to compress or extract objects in a JAR file.The following table describes the commands on the Tools menu.Table 2.4Select...Assembly ToolTools menu commandsDeployment Descriptor EditorJDataStore ExplorerTo...open the Application Assembly tool. See Chapter 8, “Using theApplication Assembly Tool” for details.open the DDEditor. See Chapter 9, “Using the DeploymentDescriptor Editor” for details.open the JDataStore Explorer. See the JDataStore Developer'sGuide for details.Using the Borland Management Console 2-5

Console main menuTable 2.4Select...SonicMQ ExplorerJNDI BrowserOptimizeIt ProfilerHelp menuTools menu commands (continued)To...open the SonicMQ Explorer tool. For additional information,refer to the SonicMQ documentation included with BorlandEnterprise Server located in the /SonicMQ/sonicmq_docs directory.open the JNDI Browser. See Chapter 9, “Using the DeploymentDescriptor Editor” for information on JNDI settings and see theBorland Enterprise Server Developer’s Guide for moreinformation.start OptimizeIt Profiler. For more information, see “OptimizeItProfiler” on page 3-9.The following table describes the commands on the Help menu.Table 2.5 Help menu commandsSelect...Installation GuideUser's GuideDeveloper's GuideDeployment Descriptor Editor (DDE)VisiBroker Developer's GuideVisiBroker Programmer's ReferenceVisiBroker GateKeeper GuideVisiNotify GuideBorland Enterprise Server Home PageTo...get online help on installing Borland EnterpriseServerget online help on using the Console and other toolsincluding the DDEditor and the ApplicationAssembly Tool. Borland Enterprise Serverget online help on packaging, deployment, andmanagement of distributed object-basedapplications.get online help on using the DDEditor.get online help on how to develop VisiBrokerapplications in Java or C++ and the configurationand management of the VisiBroker ORB.get online help on the classes and interfaces suppliedwith VisiBroker for Java and C++ and on using theprogramming tools and command-line options.get online help on the VisiBroker Gatekeeper thatenables VisiBroker clients to communicate withservers across networks while conforming to thesecurity restrictions imposed by web browses andfirewalls.get online on using the VisiNotify notificationmessage framework.access the Borland Enterprise Server web site.2-6 User’ s Guide

Setting Console preferencesTable 2.5Help menu commands (continued)Select...Borland Enterprise Server News GroupAboutTo...access the Borland Enterprise Newsgroups web site.open a dialog box containing the following tabs:About: Shows the Borland Enterprise Server versionnumber and copyright information.General System Information: Shows various systemconfiguration settings that Borland Enterprise Serverhas detected such as the operating system, Javaversion, Java vendor, Java Compiler, and so forth.Java Properties: Shows the Java virtual machineproperty settings in use by Borland EnterpriseServer.Setting Console preferencesConsole preferences enable you to specify configuration, operation, and appearancesettings used by the Console such as the SmarAgent port, the default polling intervalfor performance information displayed in the Console, and so forth.To set Console preferences:1 Start the Console and choose Preferences from the Console menu. A dialog boxappears with a list of preferences grouped into the following tabs:• General – see “General tab” on page 2-7• Discovery – see “Discovery tab” on page 2-8• Security – see “Security tab” on page 2-9• State – see “State tab” on page 2-9• Statistics – see “Statistics tab” on page 2-10• Logs – see “Logs tab” on page 2-10• Tools – see “Tools tab” on page 2-112 Navigate through the tabs and select the preferences as desired. (If you want torestore the settings shown on a particular tab to the values last saved, click Reset.)3 When you have finished making your selections, click OK.The following sections provide details on each of the Preferences tabs.General tabThis tab provides the following options:• Look and feel: Sets the display format and behavior of the Console windows. Theavailable options are: Metal, Windows or CDE/Motif.Using the Borland Management Console 2-7

Setting Console preferences• Tab Memory: Specifies the view state information the Console uses. The followingoptions are available:• Don't Remember last visited tab pane: Tells the Console to open each node inthe tree with the General tab displayed on the right.• Remember last visited tab pane by type: Tells the Console to open a node onthe same type of tab (on a similar node) that was most recently viewed. Forexample, if the Logs tab is currently in view and you click on another node thathas a Logs tab, the Console first displays the Logs tab for that node.• Remember last visited tab pane by type and name: Tells the Console to open anode that had been expanded earlier in the Console session to the tab that waslast in view when that node was selected.• Sound beep on errors: If checked, the Console sounds an alarm when an erroroccurs.• Enable debug output: Tells the Console to report debugging information in theErrors pane at the bottom of the Console.Discovery tabNoteImportantThis tab provides the following options:• Autodiscover servers on local subnet: Enables the Location Service and/or theNaming Service to automatically locate all Borland Enterprise Servers using aspecified Management Port on the local area network and display them in theConsole. It is strongly recommended that you do not change this value.Use of the Location Service is recommended, especially when you aretroubleshooting, because it always shows what is actually running. The NamingService performance, however, is faster on heavily-loaded systems.Autodiscover servers via proxy servers: Enables the Location Service or theNaming Service, or both, to automatically locate all Borland Enterprise Serversusing a specified management port that are hosted on a specified proxy server.• Enter an explicit list of servers: Lets you manually specify which servers displayin the Console.• Show server host in name. Check this box if you want the host name of themachine on which the server is running to be displayed next to the server name inthe Console navigation tree.The port number shown in the ”Autodiscover servers on local subnet” field on thistab is not the same as the Smart Agent port.If you change the Management port of a server that is part of a cluster, in order tomaintain the cluster's operation, you must also make the same change to theManagement port for all other servers in that cluster. Note that the Management portcan only be changed locally on the machine on which the server is installed. For moreinformation on clusters, see Chapter 5, “The Clusters View”.2-8 User’ s Guide

Setting Console preferencesSecurity tabNoteThis tab provides the following options:• Default Realm: Specifies the name of the authentication realm used by theConsole to interact with each Borland Enterprise Server.• Default User: Specifies the user name used by the Console to interact with eachBorland Enterprise Server.• Enable Security: Determines how the Console handles security:• When checked, enables the Console to communicate with a server regardless ifit has security enabled or not. When the Console receives a request from aserver with security enabled, however, the Console must first pass the user'slogin credentials (realm, username, and password) to that server forauthentication before the Console can access services on that server.• When this box is not checked, the Console will communicate only with serversthat do not have security enabled.For more information, see Chapter 6, “Configuring security with the BorlandManagement Console”.State tabThis tab provides the following options:• Enable polling for events: When checked, tells the Console to automaticallyupdate information displayed about the state of the server and services (such asrunning, stopped, and so forth). The following settings determine the timeintervals (in milliseconds) of how often the Console checks to verify the state ofBorland Enterprise Servers, and they specify how often the state of services areupdated in the tree in the Console Servers View:• Background polling interval: Determines how frequently the Console checksthe state of the server when no user interaction is initiated.• Foreground polling interval: Determines how frequently the Console checksserver state of the server when the user performs any action that causes the username server state to change, such as stopping, refreshing, or restarting a server.• Number of foreground cycles: Determines how many times within thespecified Foreground Polling Interval that the Console check the server state.• Enable background refreshes: When checked, tells the Console to automaticallyupdate information displayed about the changes in the navigation tree, such aswhen a server, service, or module is added or removed. Clear this check box toreduce the processing overhead used by Console polling activity. If this box isunchecked, however, the Console will not display changes in the navigation treeuntil the box is checked, or until you either restart the Console, or log out and logback in to the Console.Using the Borland Management Console 2-9

Setting Console preferences• Refreshes every: Determines (in milliseconds) how frequently the Consolechecks and refreshes the display of the state of the navigation tree.• State Legend: Shows the icons used by the Console to represent the various serverstates.Statistics tabThis tab provides the following options:• Select Chart type: Use the pull-down menu to select one of the following charttypes for which statistics polling is available:• Partition Memory Chart• EJB Container Performance Statistics• EJB Container Aggregate Bean States• EJB Bean States• VisiConnect Aggregate Bean States• Connection Factory States• Partition Memory Chart: The following settings apply to the type of chart selectedas described above:• Enable polling for statistics: When checked, enables the Console to update thestatistics for the selected chart type.• Polling Interval: Sets the time interval (in milliseconds) for how often objectsare sampled for performance information. This value determines how often thestatistics property tab (when available) is updated. If this box is unchecked,polling for statistics for the selected chart type is disabled.• Sample size: Specifies how many points the Console displays on the x-axis(how far back in time) of a selected chart type.Logs tabThis tab provides the following options:• Enable polling of log file contents: When checked, tells the Console to generatelog file statistics. If this box is unchecked, polling for statistics is disabled.• Polling Interval: Sets the time interval (in milliseconds) for how often log filesare updated.• Show date and times: When checked, tells the Console to include dates and timesassociated with log entries. If this box is unchecked, dates and times associatedwith log entries are not reported.• Show at most n lines: Sets the maximum number of message lines (log entries)shown. For example, if you specify 600 lines, only the last 600 lines in the log fileare shown.2-10 User’ s Guide

Console File Editor context menu commands• Refresh only if timestamp changed: When checked, tells the Console to onlyupdate the log file when dates and times associated with log entries have changed.If this box is unchecked, the Console will allays update the log file at the specifiedpolling interval.Tools tabNoteUse this tab to specify an absolute (fully qualified) path location in which OptimizeItProfiler is installed on the machine on which the Console is running. Enter a path orclick Browse to locate the local OptimizeIt installation directory. If you installed theOptimizeIt Suite, be sure to select the second level OptimizeIt folder (the folder thatcontains the lib directory, as well as other directories).If you are using the Console to manage a remote server, you must also installOptimizeIt on the machine on which the server is running.For more information, see “OptimizeIt Profiler” on page 3-9.Console File Editor context menu commandsThe following table shows the context menu (right-click) commands you can usewhen viewing or editing a configuration file in the Console file viewer and editwindow. The file viewer is available on the XML tab for Deployed Modules. The editwindow is available on certain tabs in various configuration windows such as thosefor the Apache and SonicMQ services described below, and for all files viewed in theInstallations view (see Chapter 4, “The Installations view”).Table 2.6Choose...CutCopyPasteSelect AllFind...Find againReplace...Go to line...Context Menu CommandsTo...delete selected text.store selected text in memory so that it can be pasted.insert text that was copied.select the entire contents of the file.open the Find/Replace dialog box that lets you search for and replace a specifiedstring.repeat the previous Find command to search for the next occurrence in the file forthe specified string.open the Find/Replace dialog box that lets you search for and replace a specifiedstring.open the Go to line number dialog box that lets you specify the line number onwhich to position the insertion point.Using the Borland Management Console 2-11

Starting a serverStarting a serverNoteBorland Enterprise Server can be installed and started either locally or on a sharedmachine. The server, in turn, starts all services configured for the server. Theseservices include the Web container, database, SmartAgent, EJB containers, JNDIServices, SonicMQ, and so forth. You can start a server as described below.On Linux installations, the Borland Enterprise Server cannot run as root and the Kornshell must be installed.Starting a server from the Windows DesktopTo start a server using from the Windows desktop, double-click the BorlandEnterprise Server icon on your desktop, or click the Windows Start button andchoose Server from the Borland Enterprise Server program group.Starting a server using the ConsoleNoteTo start a server using the Borland Management Console:1 Open the Console and select the Installations View.2 Click on the node in the Installations tree that represents the name of a server thatis installed on the same machine on which you are running the Console, thenright-click and choose Start from the context menu.When you start a server from the Console, the command window does not displayversion or message information as it does when you issue the ias command from thecommand line.Starting a server from the command lineTo start a server from the command line:1 Open a command window.2 Use the following command syntax to start a Borland Enterprise Server and setoptions:ias [options] [args]The server that is started is determined by the path associated with the ias command.The path must be a valid Borland Enterprise Server installation directory. Fordescriptions of the options available for the ias command, see “ias commandoptions” on page 2-14.The ias command specifically limits the number of changes to the server'sconfiguration or its execution environment. This functionality ensures a consistentand reliable startup. Server configuration, including which services are started, areall controlled by a set of properties that are pre-configured into the server. Unless2-12 User’ s Guide

Stopping a serverexplicitly changed by the server administrator, these properties remain consistentacross server invocations.Stopping a serverNoteOccasionally, you may need to stop the Borland Enterprise Server. When you stopthe server, all services supported by the server are terminated (including serversupport for the Console).To stop the server:1 Select the Servers view in the Console.2 Click on the node in the tree that represents the server you want to stop.3 Right click and choose Stop from the Context menu.After a few moments, the server stops. When you restart the server, all services thatwere marked as started in the Console are restarted automatically.You can also stop a server from a command window by pressing CTRL+C.Configuring a serverNoteTo configure a server using the Console:1 Switch to the Servers View in the Console and select the node that represents thename of the server in the tree.2 Right-click on the node and choose Configure.3 When you have completed your changes on the Configure Server dialog box,choose OK.For detailed descriptions of the properties on the Configure Server dialog box, clickthe Help button.Configuring a server from the command lineImportantYou can use the ias command to start the Borland Enterprise Server. This sectiondescribes how to use the Borland Enterprise Server command-line options to changehow the server is configured when you start it.Take care using command-line options. These options are provided to enableapplication developers and testers to quickly test different server and environmentconfigurations. In a production environment, the server should always be startedwith a consistent set of options.Also, to avoid situations where the server behaves differently when started bydifferent users, care should be taken when using options to reference environmentvariables.Using the Borland Management Console 2-13

Configuring a server from the command lineNoteTo ensure consistent starting, server administrators can predefine command-lineoptions and store them in the server's java.options file (install_dir/bin /ias.config).ias command optionsThe following table describes the ias command options:Table 2.7Option-help-version-debug-service-Java VMias command optionsDescriptionPrints a summary of command syntax and options.Prints product version and configuration information. Version information isprovided for the server and all related services.Runs the server with debug information enabled. Debugging information is usefulfor checking the server configuration and providing troubleshooting informationto Borland Technical Support. The debug option displays all settings used toinvoke the Java Virtual Machine (JVM) including all paths used to find the JVM.-remove Uninstalls this Windows service.-classicvm Selects the Classic VM.-hotspotvm Selects the HotSpot VM.-clientvm Selects the HotSpot Client VM 2.0 [JDK 1.3].-servervm Selects the HotSpot Server VM 2.0 [JDK 1.3].-javahome Specifies the installation directory of the Java VM.-remove Uninstalls this Windows service.-classpath Same as -classpath/a-classpath/a Appendsto the classpath from the config file.-classpath/p Prependsto the classpath from the config file.-classpath/r Replacesthe classpath from the config file.-D= Sets a Java system property.-verbose[:{class|gc|jni}] Enables verbose output from the Java VM.-X Prints a summary of nonstandard command options. (The -X options arenonstandard and are subject to change without notice.) -server Selects theserver to run.Editing the ias.config fileYou may sometimes need to edit the configuration profile of your application serverto ensure consistency and reliability in starting procedures. Some reasons that youmay need to make such changes include:• A change in the Java Virtual Machine being used.• Changes to the properties of the Java Virtual Machine being used.• Ensuring that certain information is added to a path or classpath.2-14 User’ s Guide

Configuring the server for multiple network interfacesIn such circumstances, open the file install_dir/bin/ias.config and insert the requiredchanges there.Configuring the server for multiple network interfacesIf your host computer has more than one network interface (for example, a portablecomputer with two network cards), you must configure the Borland EnterpriseServer to communicate across both network interfaces. This is required for the SmartAgent to work correctly.To support multiple network interfaces on your computer:1 Open the Console, choose the Servers view, and navigate to the Services node inthe tree.2 Select the Smart Agent service, then right-click and choose Configure from thecontext menu.3 Select the Local Address File tab which displays the localaddr file that contains adescription of your computer's network interfaces.The localaddr file contains a line for each network interface used by your computer.Each line includes an IP address, subnet mask, and broadcast address. For example,the localaddr file includes information for two network interfaces:216.64.15.10 255.255.255.0 216.64.15.255214.79.98.88 255.255.255.0 214.79.98.255Windows: On the Windows platform, you can view the appropriate networkinterface values for your computer by selecting the TCP/IP protocol properties in theNetwork Control Panel.UNIX: On UNIX, you can use the following command to view the appropriatenetwork interface values for your computer:ifconfig -aUsing the Borland Management Console 2-15

Working with separate subnetworksFigure 2.2Local Address File tabWorking with separate subnetworksIf you use Borland Enterprise Servers on two or more subnetworks, you mayencounter problems locating objects across subnetworks.Smart Agents that use the same UDP Broadcast port automatically locate each otheron the same local network. However, many sites do not allow UDP broadcasts tocross subnetworks. In these cases, Smart Agents on separate subnetworks cannotcommunicate with each other.To correct this situation:1 Open the Console, select the Servers view, and navigate to the Services node in thetree.2 Select the Smart Agent service, then right-click and choose Configure from thecontext menu.3 Select the Address File tab which displays the agentaddr file that contains an IPaddress for each Smart Agent that needs to communicate. This IP addressrepresents the host where the Smart Agent is running.For example, the following file includes information for two Smart Agents:199.10.9.5101.10.2.62-16 User’ s Guide

Starting a default serverFigure 2.3Address File tabStarting a default serverNoteTo start a default version of the server:• WinNT: Double-click the Borland Enterprise Server icon on your desktop, or clickthe Windows Start button and choose Borland Enterprise Server from the BorlandEnterprise Server program group.• WinNT/UNIX: Open a command window and type the following:iasTo recognize the ias command, your path system variable must include the BorlandEnterprise Server bin directory (install_dir/bin), or you can enter the path explicitly.Once the server has started, you can use the Console to specify which services arestarted with the server. For more information, see Chapter 3, “The Servers view”.Starting the VisiBroker ConsoleThe VisiBroker Console comprises of a user interface and tools for managing theVisiBroker ORB and services.To start the VisiBroker Console:1 Start the Borland Management Console.2 Select VisiBroker from the left most button bar of the Console to launch theVisiBroker Console.Using the Borland Management Console 2-17

2-18 User’ s Guide

Chapter3Chapter3The ServersviewImportantUse the Servers view in the Management Console to view servers on the network andmanage the services, partitions, and deployed modules of a server.The Servers view contains the following areas:• A navigation tree on the left side of the Management Console that provides anexpandable and collapsible browser that shows the servers on the network thatmatch the current login credentials (user name, password, security realm as wellas the Discovry tab settings in use (see the “Discovery tab” on page 2-8), plus theservices, partitions, partition services, and modules each server contains. To viewor modify an object in the tree, navigate to it by expanding its icon (node). If theobject in the tree contains other objects, you can also double-click the icons toexpand the view.• An pane that opens beneath the navigation tree and lists the XML descriptor filesassociated with an archive selected in the navigation tree. This pane is hiddenfrom view if there are no XML descriptor files associated with the selectedmodule.• A pane on the right side of the Management Console that displays the tabsdescribed in the sections below.• A log pane at the bottom of the Management Console that opens when a server orservice generates warnings or errors.For documentation updates, go to www.borland.com/techpubs/bes.Tabs on the right paneThe right pane displays a variety of tabs that contain additional information aboutthe object selected in the tree. The tabs vary depending on the object being viewedand may include:• General (always available)The Servers view 3-1

Context menu commands in the Servers view• License (available for the Server only to update license and register Server)• Memory (available for Partitions)• Logs (available for Shared services)• Statistics (available for EJB Containers)• Bean States (for EJB Containers)• Properties (available when additional properties apply)• Engine (available for HTTP and IIOP services)• Connector (available for HTTP and IIOP services)• Host (available for localhost)• Factory States (available for VisiConnect)• Details (available for Deployed Modules)• XML (available for Deployed Modules)• Axis (available for the Axis message processing framework service).Context menu commands in the Servers viewIn addition to the commands on the Management Console main menu, othercommands are available from a context menu (right-click) in the Servers view whenyou select a node in the tree browser. The commands that are available from thecontext menu vary depending on the type of node that is selected. The Servers viewalso lets you select multiple nodes in the tree simultaneously. If the nodes selectedare all of the same type (such as deployed modules, for example), only the actionsthat are common to all nodes will be enabled in the context menu and bulk actionscan be performed.The following table shows the context menu commands (right-click) you can use onthe tree in the Servers view.Table 3.1CommandRestartUpdate portsStartStopKillNew PartitionContext Menu CommandsDescriptionShuts down and restarts the server or service.Invokes the Port Configuration wizard that help you modifythe user and management ports of a server. This command isonly available for the default and server nodes.Starts a stopped server or service.Exits the server or service normally and writes data to disk asneeded.Terminates the server or service immediately.Creates a new Partition with the default deployed modulesand Partition services on the Borland Enterprise Server. Thiscommand is only available for Partition nodes.3-2 User’ s Guide

Table 3.1CommandCloneDeletePingDump stack to logRemoveRedeployDownload copy of moduleGenerate client jarsEdit with deploymentdescriptor editorEdit with assembly toolExport EJB as a Web ServicePerformance tuningEnableDisableConfigureUpdate LicenseRegister ServerContext Menu Commands (continued)Context menu commands in the Servers viewDescriptionMakes an identical copy of a Partition including its contentand configuration settings. This command is only available forPartition nodes.Deletes a partition or a deployed module.Checks to see if a server or service is active. This command isonly available for servers, services, and Partition services.Checks diagnostic information about the threads running in aPartition and causes the Partition to perform a thread dumpinto its own event log (accessed on Logs tab). This command isonly available for server and Partition nodes.Removes a deployed module from a Partition. This commandis only available for deployed modules nodes.Invokes the Module Deployment Wizard that lets you deployan application such as a J2EE module and its components to acontainer. This command is only available for deployed modulesnodesLets you save a module under a new name and location. Thiscommand is only available for deployed modules nodes.Invokes the Stub Generation Wizard that lets you generatestub classes and store them in various archives types. Thiscommand is only available for deployed modules nodesOpens the selected module in the Deployment DescriptorEditor (see Chapter 9, “Using the Deployment DescriptorEditor”). This command is only available for deployed modulesnodesOpens the selected module in the Application Assembly Tool(see Chapter 8, “Using the Application Assembly Tool”). Thiscommand is only available for deployed modules nodesInvokes the Export EJB as a Web Service wizard that lets youexport a stateless Session bean as a Web service. Thiscommand is only available for stateless Session bean nodes.Invokes the Partition Performance Tuning wizard. Thiscommand is only available for Partition nodes.Activates a partition service or a deployed module. Thiscommand is only available for Partition services and deployedmodules nodes.Deactivates a partition service or a deployed module. Thiscommand is only available for Partition services and deployedmodules nodes.Opens a dialog box showing the properties you can edit. Thiscommand is only available for server, services, and Partitionservices nodes.Lets you update the license information (serial number ad key)that was supplied when you installed the Borland EnterpriseServer. This command is only available for server nodes.Invokes the Borland Enterprise Server registration wizard.This command is only available for server nodes.The Servers view 3-3

Borland Enterprise Server's servicesBorland Enterprise Server's servicesThe services provided with Borland Enterprise Server are divided into twocategories:• Partition Services that may be started and stopped on a per-instance basis.• Shared Services that are available to all applications running on the server.Partitions and Partition ServicesPartitions provide containers and services for hosting your applications. Any or all ofa Partition's containers and services can be enabled or disabled. A server can havemultiple partitions, and because each partition is a separate process, applicationfunctions can be distributed across multiple processes (partitions).Additionally, a partition can be cloned on the same server or on another BorlandEnterprise Server located on the same local area network. Cloning a Partition cansave significant time in the deployment process because it not only copies all of thedeployed modules, but also copies all associated service configurations settingswhich can require a considerable amount of time and effort to complete.Application components are hosted in either the Web container or EJB container, orsimply in the partition itself (in the case of Connectors). You can deploy applicationEARs or smaller archives to partitions. The partitions are ”smart” and will place yourapplication components in the proper containers. Since you may create as manypartitions as you wish, you can also have as many container instances as you wish.Borland provides up to two different containers per partition instance:• Web container (Tomcat 4.1) — for hosting JSPs and servlets, and• EJB container (Borland) — for hosting EJB componentsEach partition also provides Partition Services and J2EE APIs as Partition Services.These services and APIs are:• Naming Service — in Borland Enterprise Server, the Naming Service is managedby the VisiBroker ORB• JDataStore — Borland's all-Java database• JDBC — for getting connections to and modeling data from databases• VisiConnect — for hosting J2EE Connector Architecture Resource Adapters,getting connections to and modelling data from Enterprise Information Systems(EIS)• Java Mail — a Java email service• JTA — the Java transactional API• JAXP — the Java API for XML parsing• JNDI — the Java Naming and Directory interface3-4 User’ s Guide

Partitions and Partition Services• RMI-IIOP — remote method invocation (RMI) carried out via Internet Inter-ORBProtocol (IIOP)Configuring a PartitionNoteTo configure a Partition:1 Switch to the Servers View in the Management Console and select the node thatrepresents the Partition name in the tree.2 Right-click on the node and choose Configure.3 When you have completed your changes on the Configure Partition dialog box,choose OK.If a Partition is running when you change its configuration, the Management Consoleprompts you to choose if you want to restart the Partition to reflect your changes. Ifyou choose no, the settings on the Configure Partition dialog box will show yourchanges, but the non-editable Properties tab will show the settings that are actually ineffect which are those settings in effect when the Partition was started.For detailed descriptions of the properties on the Configure Partition dialog box,click the Help button.Creating a PartitionTo create a Partition:1 Switch to the Servers View in the Management Console.2 Select the Partition node under the server on which want to create a new a name inthe tree.3 Right-click on the Partitions node and choose New Partition.4 Enter a unique name in the Create Partition dialog box, then click OK.Cloning a PartitionTo clone Partition:1 Switch to the Servers View in the Management Console.2 Right-click on the node in the tree that represents the Partition that you want toclone and choose New Partition.3 Enter a unique name in the Clone Partition dialog box, then click OK.The Servers view 3-5

Partitions and Partition ServicesControlling the start order of Partitions on a serverNoteThe Management Console lets you determine the order in which Partitions on aserver are started when a server is started or restarted. To specify the Partition startorder for a server:1 Switch to the Servers View in the Management Console and select the Partitionsnode, then right-click and choose Configure.2 On the Partitions Start Order tab, select a Partition in the list.3 Click the Move Up or Move Down button to change the position of the Partition inthe list.4 When you have completed your changes, choose OK.For detailed descriptions of the properties on the Configure Partition dialog box,click the Help button.Explicitly-Pathed PartitionsYou can create a Partition pathed to a place other than the Borland Enterprise Serverinstall footprint. These Partitions can be hosted by local server instance.Creating an explicitly pathed PartitionTo create an explicitly pathed Partition at :1 Assemble a Partition footprint• Export an existing Partition, then un-jar the resulting archive into, or• Manually assemble the Partition footprint from a particular server's defaultpartition. Assuming you have installed BES at , copy thefollowing nodes and contents of:/var/defaults/adm/properties/partitions/standard/var/defaults/partitions/standardinto .• Give the Partition a unique Name. Each Partition within a server must beuniquely named. To set the name for the new Partition:• Rename the Partition's property and instance directories:/adm/properties/partitions//partitions/• Edit/adm/properties/partitions//service.propertiesand set the property service.name to the /adm/properties/partitions/. During this process, provide your Partition with adescription by setting the service.description property, if desired.3-6 User’ s Guide

Partitions and Partition Services2 Tell the new Partition about BES. You need to edit your Partition'smanagement_vbroker.properties file to point to the proper paths for some services:• Edit the management_vbroker.properties file in the/adm/properties/partitions/directory and locate the vbroker.security.vault andvbroker.security.domain.management.rolemap_path properties. Sethese propertiesto path to the server's management vault and management_config.jaas file.Typically these paths are:/var/servers//adm/security/management_vaultand/var/servers//adm/security/management.rolemaprespectively.• Edit/adm/properties/partitions//service.propertiesand set:container.classloader.classpath=/lib/tomcat/jasper/jaspercompiler.jar;/lib/tomcat/jasper/jasper-runtime.jarYou can put any number of Partitions under a . Simply repeat theabove steps for each Partition.If you assembled the Partition from a Partition that has been custom-configured, youshould check for any additional Step 3 configuration data that might require extraconfiguration. Similarly, if you subsequently clone a new Partition from an existingexplicitly-pathed Partition, the resulting Partition may also need extra configuration.Running an explicitly pathed PartitionPartitions can either run under the server management agent or as an unmanagedstandalone Partition using the partition command.Server-managed PartitionTo configure the server to manage and run the Partition, edit:/var/servers//adm/server.propertiesand add the to the propertyserver.service.partition.external.roots.You can configure a number of different explicitly-pathed Partition roots by addingthem as a space separated list in this property's value.Standalone PartitionTo run a standalone Partition, use the partition command and pass the additionalargument -partition.root for the explicitly-pathed Partition beingstarted.The Servers view 3-7

Partitions and Partition ServicesEJB containerThe Borland Enterprise Server provides integrated EJB container services. Theseservices allow you to create and manage integrated EJB containers or EJB containersacross multiple partitions. Use this service to deploy, run, and monitor EJBs. Toolsinclude a Deployment Descriptor Editor (DDE) and a set of task wizards forpackaging and deploying EJBs and their related descriptor files. EJB containers canalso make use of Connectors and so enable J2EE applications to access EnterpriseInformation Systems (EISs).JDataStoreBorland's JDataStore is a relational database service written entirely in Java. You cancreate and manage as many JDataStores as desired. For more information onJDataStore, see the online documentation at http://www.borland.com/techpubs/jdatastore or from the Borland Enterprise Server Management Console's Help menu.Starting the JDataStore ExplorerTo start the JDataStore Explorer, choose JDataStore Explorer from the Tools menu, orclick the Launch the JDataStore Explorer icon in the tool bar.Naming ServiceThe Naming Service is provided by the VisiBroker ORB. It allows developers,assemblers, and/or deploys to associate one or more logical names with an objectreference and store those names in a VisiBroker namespace. It also allows applicationclients to obtain an object reference by using the logical name assigned to that object.Session ServiceThe Java Session Service (JSS) is a service that stores information pertaining to aspecific user session. The JSS provides a mechanism to easily store sessioninformation into a database. For example, in a shopping cart scenario, informationabout your session (your login name, the number of items in the shopping cart, andsuch) is polled and stored by the JSS. So when a session is interrupted by a TomcatWeb Container unexpectedly going down, the session information is recoverable byanother Tomcat instance through the JSS. The JSS must be running on the localnetwork. Any Tomcat instance (in the cluster configuration) will find the JSS, connectto it and continue session management.Transaction ServiceThe Transaction Service provides a Transaction Manager that is implemented on topof the VisiBroker ORB and simplifies the complexity of distributed transactions byproviding an essential set of services—including a transaction service, recovery and3-8 User’ s Guide

Partitions and Partition Serviceslogging, integration with databases, and administration facilities—within one,integrated architecture. The Transaction Manager provides distributed transactionssupport, though recoverable two-phase transactions is supported.VisiConnect ServiceThe Borland Enterprise Server provides integrated Connector container services inthe VisiConnect Service. These services allow you to create and manage integratedConnector containers or Connector containers across multiple partitions. Use thisservice to deploy, run, and monitor Connectors Resource Adapters to connect toEnterprise Information Systems (EIS). Tools include a Deployment Descriptor Editor(DDE) packaging and deploying Resource Adapters and their related descriptor files.Web containerThe web container is designed to support development and deployment of webapplications or the web components of other applications (for example, servlets, JSPfiles, and such). The Borland Enterprise Server provides an implementation ofTomcat 4.1 as its web container. Tomcat is a sophisticated and flexible open-sourcetool that provides support for servlets, Java Server Pages, and HTTP. Borland hasalso provided an IIOP Connector module with its implementation of Tomcat,enabling communication with application components and the web server over IIOPrather than strict HTTP.OptimizeIt ProfilerBorland's OptimizeIt Profiler (purchased separately) helps you track memory andCPU usage issues during the development of Java applications. Borland EnterpriseServer runs OptimizeIt at the Partition level.NoteEnabling a Partition to run with OptimizeIt ProfilerTo run a Partition with OptimizeIt enabled:1 Install OptimizeIt on the machine on which the Management Console is running.If you are using the Management Console to manage a remote server, you mustalso install OptimizeIt on the machine on which the server is running.2 From the Management Console menu, select Preferences, then select theOptimizeIt tab.3 Enter the absolute (fully qualified) path location in which OptimizeIt is installedon the machine on which the Management Console is running. Enter the pathexplicitly or click the Browse button to locate the local OptimizeIt installationdirectory. If you installed the OptimizeIt Suite, be sure to select the second levelOptimizeIt folder (the folder that contains the lib directory, as well as otherdirectories).4 Select the Servers view if it is not already active.The Servers view 3-9

Partitions and Partition ServicesNote5 Expand the navigation tree to the node that represents the Partition on which youwant to enable OptimizeIt.6 Right click on the Partition node, then select Configure.7 Select the OptimizeIt tab and check the Start Partition using Borland OptimizeItbox.8 Enter the absolute (fully qualified) path location where OptimizeIt is installed onthe machine on which the Server running.9 Enter the port number that was specified when OptimizeIt was installed on themachine on which you are running the server (the server that contains the selectedPartition).10 Enter any options you want to use in the Profiler options box (refer to theOptimizeIt documentation for the available options).11 Enter any additional command line arguments you may require (refer to theOptimizeIt documentation for the available options).12 Click OK.If the Partition is running when you click OK, the Management Console will promptyou to restart the Partition. If you choose Yes, the Partition will restart, but it will runmore slowly. If you choose No, or if the Partition was not running, you can start thePartition whenever you choose.Starting OptimizeIt ProfilerTo start OptimizeIt Profiler, choose OptimizeIt Profiler from the Tools menu, or clickthe Launch the OptimizeIt Profiler icon in the tool bar.J2EE APIsBorland Enterprise Server AppServer Edition is a full reference edition of the J2EE 1.3specification from Sun Microsystems. As such, many J2EE APIs are available for useby developers in the Borland Enterprise Server. These are summarized below.JDBCBorland implements the Java DataBase Connection APIs version 2.0 from SunMicrosystems. JDBC 2.0 provides APIs for writing database drivers and a full ServiceProvider Interface (SPI) for those looking to develop their own drivers. JDBC 2.0 alsosupports connection pooling and distributed transaction features.Java MailJava Mail is an implementation of Sun's Java Mail API. It is a set of abstract APIs thatmodel a mail system. The API provides a platform independent and protocolindependent framework to build Java-technology-based email client applications.3-10 User’ s Guide

Partitions and Partition ServicesJTAThe Java Transactional API (JTA) defines the UserTransaction interface required byapplication components to start, stop, rollback, or commit transactions. EJBs establishtransaction participation through the getUserTransaction method, while othercomponents do so using JNDI lookups. JTA also specifies the interfaces needed byConnectors and resource managers to communicate with an application server'stransaction manager.JAXPThe Java APIs for XML Parsing (JAXP) enable the processing of XML documentsusing the DOM, SAX, and XSLT parsing implementations. Developers can easily usethe parser provided with the reference implementation of the API to XML-enabletheir Java applications.JNDIThe Java Naming and Directory Interface is used to allow developers to customizetheir application components at assembly and deployment without changes to thecomponent's source code. The container implements the runtime environment for thecomponents and provides the environment to the component as a JNDI namingcontext. The components methods access the environment through JNDI interfaces.The JNDI naming context itself stores the application environment information andmakes it available to all application components at runtime.Starting the JNDI BrowserTo start the JNDI Browser, choose JNDI Browser from the Tools menu, or click theLaunch JNDI Browser icon from the tool bar.RMI-IIOPAs mentioned above, the VisiBroker ORB supports RMI-over-IIOP protocol. Whenused in conjunction with the IIOP Connector Module for Apache and Tomcat, itallows distributed Web applications built on CORBA foundations.Other TechnologiesIt is also possible to wrap other technologies, provide them as services, and run themin the Borland Enterprise Server.Shared ServicesShared services are those services available to all applications being hosted on theBorland Enterprise Server. The shared services are:• 2PC Transaction Service• Apache 2.0 Web Server• Smart AgentThe Servers view 3-11

Partitions and Partition Services• SonicMQ Daemon2PC Transaction ServiceBorland Enterprise Server includes a two-phase commit transaction managementservice called the VisiTransact Transaction Manager (OTS). For more information ontransactions and VisiTransact, see Transaction management and JDBC in the BorlandEnterprise Server Developer's Guide.Apache 2.0 Web ServerBorland Enterprise Server includes the Apache Web Server version 2.0. The ApacheWeb Server is a robust, commercial grade reference implementation of the HTTPprotocol. The Apache Web Server is highly configurable and extensible through theaddition of third-party modules. Borland has added an IIOP Connector Module to itsimplementation of the Apache Web Server. This Connector Module allows Apacheand the Tomcat Web container (see below) to communicate via Internet Inter-ORBProtocol (IIOP), allowing users to add the power of CORBA with their Webapplications in new ways. For more information about the Borland Enterprise ServerApache implementation, go to Developer's Guide.NoteNoteConfiguring the Apache 2.0 Web ServerTo configure the Apache 2.0 Web Server:1 In the Management Console, go to the Servers view.2 In the Navigation pane tree, right-click the Apache 2.0 node and choose Configure.3 When you have completed your changes on the Configure Apache 2.0 dialog box,choose OK.For detailed descriptions of the properties on the Configure Apache 2.0 dialog box,click the Help button.Smart AgentThe Smart Agent is a distributed directory service provided by the VisiBroker ORBused in the Borland Enterprise Server. The Smart Agent provides facilities used byboth client programs and object implementations, and must be started on at least onehost within the local server network.Users of the Web Edition do not have to use the Smart Agent if they expect their webserver and web containers to communicate through HTTP or another web protocol.To leverage the IIOP Connector Module (and, by extension, the ORB provided withthe Web Edition), however, the Smart Agent must be turned on, although it is onlyconfigurable in the VisiBroker and AppServer Editions.Configuring the Smart AgentTo configure the Smart Agent:1 Switch to the Servers View in the Management Console and select the Smart Agentnode in the tree.3-12 User’ s Guide

Viewing log filesNote2 Right-click on the Smart Agent node, and choose Configure.3 When you have completed your changes on the Configure Smart Agent dialogbox, choose OK.For detailed descriptions of the properties on the Configure Smart Agent dialog box,click the Help button.SonicMQ DaemonBorland provides the SonicMQ Broker as a Shared Service for the Borland EnterpriseServer. The SonicMQ Explorer is launched from the Borland Enterprise ServerManagement Console, Tools menu. SonicMQ is a full implementation of the JavaMessaging Service (JMS) APIs from Sun Microsystems. It is highly scalable andflexible service that provides support for XML as well as participation in XAtransactions and other business methods.NoteNoteStarting SonicMQTo start SonicMQ, choose SonicMQ Explorer from the Tools menu, or click theLaunch the SonicMQ Explorer icon in the tool bar.For additional information, refer to the SonicMQ documentation included withBorland Enterprise Server located in the /SonicMQ/sonicmq_docs directory.Configuring SonicMQTo configure SonicMQ:1 Switch to the Servers View in the Management Console and select the SonicMQBroker node in the tree.2 Right-click on the SonicMQ node in the tree, and choose Configure.3 When you have completed your changes on the Configure Server SonicMQ,choose OK.For detailed descriptions of the properties on the Configure Server SonicMQ dialogbox, click the Help button.Viewing log filesLog files provide a collection of error and status messages associated with a service.If problems occur, these files are useful for troubleshooting.To view the log file for a service:1 Navigate to the service listed in the tree pane that you wish to examine.2 Click the Logs tab in the right pane for the service and select the log you wish toview from the pull-down menu.• error displays all error messages produced by the service.• event displays all events recorded by the service.The Servers view 3-13

Server propertiesNoteA list of log file entries appears in the right pane.You can use the Management Console preferences to control how many messagelines are displayed in the log files and how often the log display is updated.Server propertiesConfiguration properties for each server appear on the following tabs:• Server General tab• Server Properties tab• Server License tabServer General tabThe following properties appear on the General tab for each server and are groupedinto two categories: General Properties and Server Properties.The General Properties are:• Name: Specifies the name of the service or entity.• Version: Specifies the version of software for service or entity.• Vendor: Specifies the vendor of the server software.• Description: Specifies the description of the server.The Server Properties are:• Edition: Specifies the product edition that has been purchased.(Web Edition,VisiBroker Edition, and AppServer Edition). Each of these editions builds uponthe tools and services of its predecessor. The most basic of the editions is the WebEdition, the most versatile is the AppServer Edition. You can upgrade from oneEdition to another, if desired.• Cluster: Specifies if the server is part of a managed cluster. For more information,see Chapter 5, “The Clusters View”.• Updates: If you download a patch from the Borland web site and install it usingthe correct instructions, the name, version and details of the patch will appear inthe Updates window. Double-clicking on a patch will launch a Read-me file for thepatch. All patches applied since the Borland Enterprise Server installation willappear in a list.Server Properties tabThe following properties appear on the Properties tab for each server:• Smart agent port: Specifies the Smart Agent port used by the server.3-14 User’ s Guide

Partition propertiesPartition General tabThe following properties appear on the General tab for all Partitions and services:• Name: Specifies the name of the service or entity.• Version: Specifies the version of the software for the service or entity.• Vendor: Specifies the vendor of the software for the service or entity.• Description: Specifies the description of the service or entity.The following sections describe the additional properties that display for eachpartition and service.Partition propertiesIn addition to the General Properties described above, the following propertiesappear on the General tab for each Partition:• Path of Partition on Server: Specifies the absolute path location of the Partition onthe machine on which the server is running.• Verify all modules when loaded: Determines if the Partition performs deployerrole verification of all the modules it contains as they are loaded. The default istrue.Security SettingsThe following security related properties appear on the General tab for eachPartition:• Security enabled: Specifies if the Borland Enterprise Server security service isrunning on the selected partition. The default is false.• SSL enabled/disabled: Specifies if the services in the selected partition are using aSecure Socket Layer. The default is true.Partition Properties tabThe following properties appear on the Properties tab for each Partition:Virtual Machine• Enable JPDA Remote Debugging: Enables you to debug a Partition's servicesusing JPDA (Java Platform Debugger Architecture).• JPDA Debugging Transport Address: Specifies the socket port number at whichto listen for a debugger application. If no address is specified, one is automaticallyselected and written to the Partition's event log.• Suspend Partition Until Debugger Attaches: If set to true (the default), disablesthe Partition until the debugger attaches.3-16 User’ s Guide

Server Connection Manager SettingsPartition properties• Server connection manager name: Specifies the name of the connection.• Listener port: Specifies the port number on which the ORB listens for connectionsfor services in this Partition. 0 means the system will pick a random port number.• Connection Pool:• Maximum number of connections: Specifies the maximum number ofconnections allowed into the Partition.• Maximum connection idle time: Specifies the maximum time a connection isallowed to remain in the connection pool before it is reaped from the pool.• Dispatcher Pool:• Maximum number of threads: Specifies the maximum number of dispatcherthreads that the Server Connection Manager can create.• Minimum number of threads: Specifies the number of dispatcher threads thatthe Server Connection Manager creates at initialization. The number of threadsis not allowed to fall below this limit.• Maximum thread idle time: Specifies the time (in seconds) before an idledispatcher thread will be reaped.For more information, see Chapter 6, “Configuring security with the BorlandManagement Console”.Class Loading tabA classloader policy determines the type of classloader to be used by the Partition.Valid values are per_module or container. The per_module classloader creates aseparate classloader for each deployed module. This policy is required if you want tobe able to hot deploy. The container policy sets up a single classloader that allmodules within the partition will use. If this policy is selected, you cannot hotdeploy.This read-only pane displays a tree with classloaders per module. It shows themodules loaded with each classloader and the search order of the modules in aclassloader.Monitoring tabThe Monitoring tab lets you view the memory resource allocations and thread countsin use by the selected Partition:• Maximum Heap Available: Shows the amount of memory allocated to the JVM.• Current Heap Used: Shows the amount of virtual memory available.• Current Active Threads: Shows the amount of current active threads.The Servers view 3-17

Deployed modulesThe icons in the toolbar at the top of the tab let you switch the view between an areachart, line chart, or tabular data format; provide a shortcut that opens the Statisticstab, and let you toggle the display of the chart legend on or off. You can enable/disable polling for statistics, select polling intervals (ms) and sample size (default 20)for the memory charts on the Statistics preferences tab.Deployed modulesThis section describes how to use the Borland Management Console to managedeployed J2EE modules. The modules are the basic deployable units of anapplication and include EARS, WARs, RARs, EJBs and client JARs.Viewing archive attributesDeployed modules possess a variety of attributes that you can view in theManagement Console. These attributes are shown in the General, Details, Referencesand XML tabs. Different modules may have different properties displayed,depending on what type of archives they are.General tabThe General tab lists a module's properties; name, display name, module type (suchas web or application), J2EE version, module version and a description.Module Storage and Mobility Settings pertain to hosting an archive pathed outside ofa Partition (Hosted from server path) and hosting an exploded archive on a Partition(Stored as exploded archive).• Hosted from server path. This feature allows a Partition to host any archives indirectories local to the server, known as explicitly-pathed archives. That is, thesearchives must be visible from the server's file system (they do no have to be on thelocalhost). These archives are not ”deployed to” the Partition. Rather, the Partitionmust be explicitly told to host the archive. Explicitly-pathed archives are located inthe Hosted Modules folder in the server tree.Hosted archives must be deploy-ready with all stubs and skeletons alreadyproduced. Normally, stubs and skeletons are generated at deployment. Since thesearchives are hosted, you must use the Stub Generation Wizard (see “StubGeneration Wizard” on page 7-12) on the archive you wish to host. Once thenecessary stubs and skeletons are generated, you can add the archive to thePartition.If modules are deployed to the Partition's repository, the ”Deployed” button isselected.• Stored as exploded archive. Typically, you cannot deploy an exploded (or”expanded”) archive to a Partition. This feature allows a Partition to host anexploded archive in a directory local to the server. This directory must be visiblefrom the server's file system. As with explicitly-pathed archives, explodedarchives must be deploy-ready. That is, all necessary stubs and skeletons need to3-18 User’ s Guide

Deployed moduleshave been generated before they are deployed. Exploded archives can only beexplicitly pathed archives, and are deployed to the Hosted Modules folder in theserver tree. The ”Stored as exploded archive” box is checked when indicating thata specific archive being hosted by the Partition is expanded.A typical use case for hosting exploded archives is for WARs, enabling theapplication to modify itself while it is running. Any added or modified JSPs arerecognized and dynamically hosted by the Partition in the Hosted Modules folder.WAR attributes on general tabNote that Wars display additional Web module properties on the General tab. Thecontext root and any URLs for a selected WAR appear in the Additional Web ModuleProperties section. You can select a URL in the URLs window and press the Test URLbutton to test the URL address.Details tabThe Details tab includes the contents; child modules (Jars, Wars, etc.), and meta-inf.,or the Manifest (XML files). Clicking on the column headers allows you to organizeby name, date, and so on. Double-clicking on any of the contents displays filecontents.References tabThe References tab is a read-only display available for all deployed modules,wherein all EJB references are graphically displayed and can be viewed in a varietyof ways. This tab is also in the Deployment Descriptor Editor (DDEditor).NoteXML tabThe XML tab shows the module's XML deployment descriptors which include astandard descriptor and a Borland-specific descriptor. The lower left-mostNavigation pane allows you to click on either descriptor file whose contents willappear in the work pane. For more information on standard and vendor-specificdeployment descriptors, refer to Chapter 9, “Using the Deployment DescriptorEditor”.The XML is NOT editable in this view. You can edit descriptors using the DDEditor.However, you can go to, copy and paste, etc., by right-clicking in the XML workpane.XML tab for library modulesThe XML tab for library modules is relevant to timed Partition operations such asinitialization and cleanup, or Partition Lifecycle Interceptors. It displays the XMLnecessary for library modules to register classes to respond or interact with specificfunction calls associated with Partition lifecycle events. Since only lib modules areallowed to host such code, users declare a class name and parameters (to be passed tothe function for the event) in the XML file for lib modules. For specific information onXML for library modules and Partition Lifecycle Interceptors, refer to PartitionLifecycle Interceptors in the Borland Enterprise Server Developer's Guide.The Servers view 3-19

Deployed modulesAxis properties tabThe Axis properties tab shows the elements (such as services, handlers, typemappings, and so forth) of the Axis service. For more information, refer to the Axisdocumentation located in the Borland Enterprise Server doc directory (install_dir/doc/axis).About Enterprise Archives (EARs)The Borland Enterprise Server enables you to view and manage enterpriseapplication archives, which are packaged as Enterprise Archives (EARs). EARs aredeployable units and represent an application in the server. EARs are packaged in asimilar way to JAR files and contain all of the modules and deployment descriptorsthat constitute the application.Viewing EARsTo view EARs that have been deployed to the Borland Enterprise Server:1 Open the Borland Management Console. (For details about the ManagementConsole, see Chapter 2, “Using the Borland Management Console”.2 Select the Servers view if it is not already selected.3 Expand the node that represents the server in the navigation tree, then expand thePartitions and standard nodes.4 Expand the Deployed Modules node and select the specific EAR that you want toview.The EAR includes any JAR or WAR files that may be associated with it and can havemultiple JARs and WARs1 To view the EAR attributes, select the specific EAR from the Deployed Modulesfolder node.2 Select the Details or XML tab to view the EAR's attributes.3 To open a file in the work pane, double-click the file.3-20 User’ s Guide

Deployed modulesFigure 3.1EAR attributes Details tabRemoving modules from a containerNoteTo remove deployed modules from a container:1 Select the node of the module you want to remove in the Management Console.2 Right-click the module and choose Remove from the Context menu.Removing permanently removes modules from the server.About web archivesWeb archives (WARs) can be viewed and managed in the Borland Enterprise Server.WARs can be, but are not necessarily, encapsulated within an EAR and representWeb objects exclusively. Typically, it will contain:• The Java class files and helper classes for any servlets• JSP pages and their helper classes• Static HTML documents• Applets and their class files• XML deployment descriptors; a web.xml file (per Sun's specification) and usuallya Borland-specific ”web-borland.xml” file.Viewing WARsTo view WARs that have been deployed to the Borland Enterprise Server:1 Open the Borland Management Console and select the Servers View if it is notalready in view.2 Expand the node that represents the server in the navigation tree, then expand thePartitions and standard nodes.The Servers view 3-21

Deployed modules3 Expand the Deployed Modules node and select the WAR (may be in the EAR file)that you want to view.You can view the attributes of the WAR in the Details and XML tabs. For informationabout creating a WAR archive for deployment, see Chapter 9, “Using theDeployment Descriptor Editor”.About the librariesThe libraries in Borland Enterprise Server contain classes such as JDBC drivers thatcan be shared amongst modules and are stored as JAR or ZIP files. When the librariesare used by modules they are placed on the classpath of the server.For example, if a module requires a set of drivers to access a database, those driverscan be included in a JAR, then deployed to Installed Libraries. From here, they can beaccessed by all modules that need to access that database.Viewing librariesTo view an installed library in the Management Console:1 Open the Borland Management Console and select the Servers View if it is notalready in view.2 Expand the node that represents the server in the navigation tree, then expand thePartitions and standard nodes.3 Expand the Deployed Modules node and select the library that you want to view.NoteViewing library attributesLibraries possess a variety of attributes that you can view. These attributes includethe library name, type, date size, percent (compression percentage), its packed(compressed) size and its path values.To view library attributes, select the library you want to view. The library attributeswill appear in the right pane.For more information about deploying libraries, see Datasources in the BorlandEnterprise Server Developer's Guide.About resource adaptersResource Adapters provide you with a standard and reliable means of accessing datain third-party Enterprise Information Systems (EIS). Resource Adapters are packagedas Resource Adapter Archives (RARs) which are deployed to the server. They enabletransactional access to the EIS from servlets, JSP pages, enterprise beans, J2EEApplication clients and CORBA clients. RARs use the XA_TRANSACTION mode asspecified in Sun's J2EE 1.3 specifications.3-22 User’ s Guide

Viewing resource adaptersTo view RARs that have been deployed to the Borland Enterprise Server:Deployed modules1 Open the Borland Management Console.2 Select the Servers View if it is not already in view3 Expand to the server node in the navigation tree and then expand to Partitionsnode and then to the Standard node.4 Expand the Deployed Modules node and select the RAR (which may also be in anEAR file) that you want to view.Viewing Resource Adapter informationYou can view the following types of information associated with RARs:• Attributes: RARs possess a variety of attributes that you can view. Theseattributes are shown on the Details tab, which include RAR properties, values, anddetails of classes in the RAR.• State panel: Shows connection factory instance counts (can be viewed as pie chart,line chart or in a table), connection factory state diagram, and connection factorystatistic properties (editable).To view the RAR attributes:1 Select the RAR.2 Select the type of attribute that you want to view in the work pane.To view the RAR State panel:1 Select the RAR.2 Select the factory icon for the RAR.Viewing JAR informationJava archives (JAR)s can be viewed and managed in the Borland Enterprise Server.Jars can be modules within a WAR or EAR. EJBs are encapsulated and viewed withina JAR file.Typically, Jars contain:• Java class files• Standard XML files (per Sun's J2EE specification)• Borland-specific or vendor-specific XML filesViewing JarsTo view Jars that have been deployed to the Borland Enterprise Server:1 Open the Borland Management Console and select the Servers view.2 Expand the server in the navigation tree and then expand Partitions and Standard.The Servers view 3-23

Deployed modules3 Expand the Deployed Modules folder.4 Select the JAR (may be in a WAR or EAR file) that you want to view.You can view the attributes of the JAR in the Details and XML tabs. For informationabout creating a JAR for deployment, see Chapter 9, “Using the DeploymentDescriptor Editor”.Figure 3.2Viewing JAR XMLViewing EJB informationEJBs can be viewed and managed in the Borland Enterprise Server. EJBs areencapsulated and viewed within a JAR file. Jars can be modules within a WAR orEAR.You can view the following types of information associated with EJBs:• State panel: Shows bean instance counts (can be viewed as pie chart, line chart orin a table), bean state diagram, and bean statistic properties (editable).• Statistics: Shows the statistics panel by clicking the ”Chart Preferences” button inthe States Panel. The Statistics panel allows you to edit properties that control theupdating and display of statistical performance and sate information. Theseproperties include enabling for polling statistics, polling intervals (ms), andsample size (default is 20).3-24 User’ s Guide

Deployed modulesFigure 3.3Bean statistic properties - editing preferencesEnterprise bean typesThe Borland EJB container supports three types of enterprise beans:• Stateless Session beans: In these beans, any state (if required) is maintained bythe client or in an external location such as a database. Because no state ismaintained, stateless Session beans aren't tied to any specific client. Therefore, anyavailable instance of a stateless Session bean can be used to service a client.• Stateful Session beans: In these beans, state is maintained by the enterprise bean.This means the application server manages client-bean pairs. Each instance of theenterprise bean is created on behalf of a client and is intended to be a privateresource to that client. Stateful Session beans can access persistent resources (suchas databases and files), but unlike Entity beans, they don't actually represent thedata.• Entity beans: These beans are persistent objects and represent an object view ofdata stored in permanent storage. An Entity bean lives in an EJB container in muchthe same way a record lives in a database. Unlike Stateful Session beans, Entitybeans can be accessed by multiple clients concurrently. This concurrency ismanaged by the EJB container.You can view and edit the following beans' attributes desrbied in Chapter 9, “Usingthe Deployment Descriptor Editor”:• Bean Name• Bean Type• Home Name• Remote Name• Local• Local HomeThe Servers view 3-25

Deployed modules• JNDI Home• JNDI Local Home• Bean Class• Session Type• Transaction Type• Storage TimeoutAbout EJB ContainersThe Borland Enterprise Server provides integrated EJB container services which arehosted within partitions. In addition to standard container services, the EJB containerprovides a range of transaction and persistence services and access to the J2EEservice and communication APIs. The following section describes persistencesupport for containers.NotePersistence supportModeled after version 2.0 of the EJB specification published by Sun Microsystems,the Borland Enterprise Server EJB container supports built-in persistence. Thispersistence can be bean-managed or container-managed.For bean-managed persistence, the developer overrides the ejbLoad and ejbStoremethods and provides custom code (for example, using JDBC) to transfer the datafrom the object's fields to permanent storage and vice versa. Bean-managedpersistence ties the enterprise bean to one method of persistence and requires thedeveloper to write and maintain persistence code.For container-managed persistence, Borland supplies mapping tools to map theEntity bean's field to fields in JDataStore. The Entity bean can be persisted intodifferent data sources by remapping the fields in the deployment descriptor.For more information on persistence support, see Entity Beans and CMP 1.1 inBorland Enterprise Server and Entity Beans and CMP 2.0 in Borland EnterpriseServer in Borland Enterprise Server Developer's Guide.Any JAR or Application (EAR) files present under Deployed Modules representcontained EJBs. The ”EJB Container” that appears under the Partition Services is arepresentation of the services provided by an EJB container. These services includeContainer-Managed Persistence (CMP) for database storage, a transaction service, anaming service for referencing objects, a Web container, and other services.An EJB server can have multiple partitions. Partitions are defined and configured asneeded to deploy objects on the network. You can add customized partitions for EJBcontainers for various databases (such as Oracle) and support them separately fromEJB development.3-26 User’ s Guide

Deployed modulesViewing EJB container services attributesNoteThe EJB partition services include a variety of attributes you can view and edit.Generally, to view the container services, you double-click on the partition service.To edit the services' properties, right click on the service and select Configure. Thecontainer services' attributes that are viewable include service name, version, vendor,description, and properties including error log information, trace level settings(timeout and factory name), flag setting, message-driven bean pool settings,performance and activity statistics, and bean state information.This section includes information about viewing container services' attributes. Forinformation about EJB attributes, see Viewing EJB information.To view EJB container services attributes:1 Open the Borland Management Console.2 Select the Servers view (if it is not already active).3 Expand the Partition Services node icon in the navigation tree.4 Double click the service node that you want to view.Figure 3.4 Container services' attributes - naming serviceThe Servers view 3-27

Partition ServicesAbout web containersThe Web container is designed to support development and deployment of webapplications. This version of Borland Enterprise Server provides Tomcat 4.0 as itsweb container. Web container properties are located in the two tabs of the work pane:General and Server Statistics.Viewing the Web containerTo view the Web container:1 In the Management Console, select the Servers view (if it is not already in view).2 Expand the server node icon in the navigation tree and then expand the Partitionnode icon.3 Expand Standard, Partition Services, then select Web Container.Each part of the Web Container is viewable by double-clicking the icon in thenavigation tree.Partition ServicesThe following sections describe the properties for the Partition Services whichinclude:• EJB Container properties described on page 3-28• JDataStore properties described on page 3-32• Naming Service properties described on page 3-32• “Session Service properties described on page 3-33• “Transaction Service properties” described on page 3-33• VisiConnect Service properties”described onpage 3-34• OptimizeIt Profiler (purchased separately) described on page 3-9EJB Container propertiesIn addition to the properties on the General tab, you can view the following EJBContainer properties on the Properties tab:Settings:• Trace level: Specifies the verbosity of logging to the event log.• Passivation timeout: Specifies for Stateful session beans, the amount of timeallowed to elapse before the bean's state is persisted.• Passivation factory name: Specifies the name of the JSS service that managespassivation persistence for this container.3-28 User’ s Guide

Partition ServicesFlags:• Use Pass By Value For Intra Bean Calls: When true, allows EJBs to passparameters by value when making calls to local beans. If not set, all calls must bemade by reference.• Enabled Statistics Gathering: Set to true by default. If set to false, reduces theamount of statistical information gathered by the container, resulting in improvedperformance.• Use Java Serialization (not IIOP): When true, causes Stateful session beans to beserialized using Java serialization rather than IIOP serialization.• Enable SIDL: When set, enables EJBs to be accessed using SIDL (SimplifiedInterface Description Language).Message-driven Bean Thread Pool:• Minimum number of threads: Specifies the minimum number of message-drivenbean dispatch threads allowed to exist in that thread pool.• Maximum number of threads: Specifies the maximum number of messagedrivenbean dispatch threads allowed to exist in that thread pool.• Maximum thread idle time: Specifies the maximum time a message driven beanthread is allowed to be idle before it is reaped from the pool.EJB Statistics tabThe EJB Statistics tab lets you view performance information about the Container.Performance information is useful for monitoring the amount of time the Containerspends on deployment activities such as dispatching and activation. Use thisinformation to troubleshoot network overload problems (for example, when aContainer spends a much larger percentage of time on dispatching instead ofbusiness logic).The icons in the toolbar at the top of the tab let you switch the view between an area,line, or bar chart, or tabular data format; provide a shortcut that opens the StatisticsPreferences tab; and let you toggle the display of the chart legend on or off.The EJB Statistics tab shows the following information:• Dispatch_POA: Time spent receiving the TCP request and sending the reply.• Dispatch_Home: Time spent in the container dispatching methods to EJBHomeobjects.• Dispatch_Remote: Time spent in the container dispatching methods to EJBRemoteobjects.• Dispatch_Bean: Time spent in the bean methods. Note that this is broken down indetail on a method-by-method basis.• EntityHome: Time spent in the container implementing EJBHome-relatedoperations specific to Entity beans.• Passivate_SB: Time spent passivating Stateful Session beans.The Servers view 3-29

Partition Services• BeginTx: Time spent beginning transactions.• CommitTx: Time spent committing transactions.• RollbackTx: Time spent rolling back transactions.• ResourceCommit: Time spent specifically in committing the work done on theresource (that is, in committing to Oracle).• Synchronization: Time spent in various Synchronization callbacks.• LoadClass: Time spent loading classes from EJB Jars, and so forth (startup cost).• CMP_Init: Time spent initializing the CMP engine (startup cost).• CMP: Time spent in the CMP engine (excluding other CMP tasks listed explicitly).• CMP_Update: Time spent in the CMP engine doing SQL updates.• CMP_Query: Time spent in the CMP engine doing SQL queries.• CMP_PrepareStmt: Time spent in the CMP engine preparing statements (startupcost).• CMP_GetConn: Time spent in the CMP engine getting JDBC connections (startupcost).• ORB_Activate: Time spent in the ORB allocating objects from pools.• ORB_Deactivate: Time spent in the ORB releasing objects to pools.• Jdbc_GetCon: Time spent in the Jdbc datasource to get a pooled connection.• Jdbc_NewCon: Time spent in the Jdbc datasource to get a new connection.(startup cost).• Jdbc_RegRes: Time spent in the Jdbc datasource to register a transaction resourcein transaction service.• Jdbc2_GetCon: Time spent in the Jdbc2 datasource to get a pooled connection.• Jdbc2_NewCon: Time spent in the Jdbc2 datasource to get a newconnection.(Startup cost).• Jdbc2_NewXaCon: Time spent in the Jdbc2 datasource to get a new XA-enabledconnection.(Startup cost).• Jdbc2_XaStart: Time spent in the Jdbc2 datasource starting a transaction branch.• Jdbc2_XaEnd: Time spent in the Jdbc2 datasource to end a transaction branch.• Jdbc2_RegRes: Time spent in the Jdbc2 datasource to register a resource in atransaction service.• Jdbcw_NewCon: Time spent in the Jdbc wrapper datasource to create a newconnection (startup cost).• MDB_OnMessage: Time spent executing an onMessage() method of a messagedriven bean.• MDB_GetSvrSesn: Time spent in obtaining a cached ServerSession object frompool.3-30 User’ s Guide

Partition Services• MDB_NewSvrSesn: Time spent in creating a new ServerSession object from a JMSprovider (startup cost).Bean States tabThe Bean States tab shows information about the current state of the entity beans inthe EJB Container. The tool bar at the top of the tab contains two groups of icons:• The icons on the left side of the tab's toolbar let you switch the view between a piechart, line chart, table, or diagram format; provide a shortcut that opens theStatistics Preferences tab; and let you toggle the display of the chart legend on oroff.• The icons on the right side of the tab's toolbar let you choose the type of bean stateinformation that displays in the chart which includes: aggregate, stateful, stateless,or message driven bean information.The information shown on the Bean States tab varies depending on the view andbean state type selected:• does not exist: In Borland Enterprise Server, a newly created bean instance is inthis state immediately after creation and before the appropriate context method iscalled on it (such as SessionContext for a session bean, EntityContext for an entitybean, or MessageDrivenBeanContext for a message driven bean).• set_context: Indicates a newly created session bean instance on which the EJBContainer is calling the setSessionContext() method. A session bean moves into theready state after the setSessionContext(), and ejbCreate() calls are over.• half_created: This is a transitory state while an entity bean is being created. This isthe state after ejbCreate() has been called on the bean instance, but ejbPostCreate()remains to be called.• ready: Corresponds to the ready state in the entity life cycle diagram in the EJBspecification, and method ready state in the case of a stateful session bean. Aninstance in the ready state is assigned an entity object identity. A bean is in thisstate to serve a business method. For entity beans, the count represents the sum ofthe entity beans that are currently participating in transactions plus those that areassociated with primary keys.• tx_ready: Indicates a stateful session bean that is associated with a transaction.This value corresponds to the method ready in TX state in the EJB specification.• half_completed: Indicates a stateful session bean that is in the tx_ready state andhas received a beforeCompletion callback from the transaction in which it isparticipating. After the bean receives an afterCompletion callback, the bean movesback to the ready state.• passive: Indicates a stateful session bean instance that has been removed frommemory (passivated to the disk) is said to be in PASSIVE state. The container'scaching algorithm may force the bean instance to be flushed from memory (thecontainer issues ejbPassivate on the instance). After this process completes, thecontainer saves the instance's state to secondary storage.The Servers view 3-31

Partition Services• pooled: Indicates a cached bean instance. An instance in the pooled state is notassociated with an entity object identity.• killed: Indicates a bean instance that is discarded as a result of system exceptionand goes into the killed state. Beans are usually discarded (as outlined in the EJBspecification).• unreferenced Indicates a bean that is removed from the container, for example,when enforcing a maximum pool size limit on an entity instance pool. Also, astateful session bean removed by an application goes into this state. Note thatbeans in this state are still consuming memory until garbage collection takes place(finalized).• finalized: Indicates a bean's state after garbage collection has reclaimed thememory of the bean instance. This value corresponds to the ”does not exist” statein the EJB specification (life cycle diagrams)JDataStore propertiesThe following additional properties appear on the General tab for the JDataStoreservice:• Port: Sets the port used to listen to JDBC requests.• Socket time out: Specifies the time a call to accept() in JDS will block until an IOexception is raised.• Temp Directory: Specifies the temporary directory used for all JDataStoreconnections. If no directory is specified, the current directory is used.Naming Service propertiesThe following additional properties appear on the General tab for the NamingService:• Backing store: Specifies the type of pluggable backing store to use for storingpersistent data. It can be memory, a relational database, or an LDAP directoryserver. The supported types of backing store adaptor are:• In-memory adaptor• JDBC adaptor for relational databases• DataExpress adaptor• JNDI (for LDAP only)• JDBC driver: Specifies the JDBC driver needed to access the database used as yourbacking store. The default is the JDataStore JDBC driver. Other supported driversare Sybase, Oracle, Borland Interbase, BEA Systems WebLogic, and IBM DB2.• URL: Specifies the URL location of the database that you want to access.• Login name: Specifies the login name associated with the database. The default isVisiNaming.3-32 User’ s Guide

Partition Services• Password: Specifies the login password associated with the database. The defaultis VisiNaming.• Poolsize: Specifies the number of database connections in the Borland EnterpriseServer connection pool when using JDBC Adaptor as the backing store.For more information, see "Using the Naming Service" in the VisiBroker Developer'sGuide.Session Service propertiesThe following additional properties appear on the General tab for the SessionService:• Factory Name: Specifies the name under which the Session Service registers itselfwith the Smart Agent. If not specified, Borland Enterprise Server uses a value thatis combined from the server name and the Partition name as follows: /.• Working Directory: Specifies the directory location where the Session Servicelooks for the JDataStore back end database. The default location is the workingPartition directory, for example: /var/servers//partitions/.• Persistent Store: Specifies the name of the JDataStore file which the SessionService uses as back end database. The default value is: jss_factory.jds.• User Name: Specifies the user name under which Session Service communicateswith the JDataStore back end database. The default value is: default-user-name.• Max Idle: Specifies (in seconds) the least amount of time that a session stayspresent in the back end database without getting accessed. If set to 0 (the default),the session stays in the database indefinitely.• Soft Commit: If set to true (the default), the Session Service uses the JDataStoreback end database with a Soft Commit mode enabled. Setting this property to trueimproves performance of the Session Service, but can lead to recently committedtransactions being rolled back after a system crash. For more information, see theJDataStore Developer's Guide.• Debug: If set to true, tells the Session Service to run with debug informationenabled. The default is false.For more information see Managing and configuring the JSS in the Developer's Guide.Transaction Service propertiesThe following additional properties appear on the General tab for the TransactionService:• Allow Unrecoverable Completion: When set to true, tells the Transaction Serviceto commit a transaction regardless of whether or not it was completed successfullyin the target database application. Allowing unrecoverable transactions is usefulThe Servers view 3-33

Partition Servicesfor testing deployment scenarios that involve disparate database transactionalsystems, but is not recommended for production servers because recovery androll-back operations are not available. The default is false.• Debug: When set to true, tells the Transaction Service to run with debuginformation enabled. The default is false.VisiConnect Service propertiesThe following additional properties appear on the General tab for the VisiConnectService:• Trace Level: Specifies the verbosity of logging to the event log.• Use Pass By Value For Calls: When true, allows connectors to pass parameters byvalue. If not set, all calls must be made by reference.• Enable Statistics Gathering: If set to false, reduces the amount of statisticalinformation gathered by the connector, resulting in improved performance. Thedefault is true.• Use Java Serialization (not IIOP): When true, causes connectors to be serializedusing Java serialization rather than IIOP serialization.Factory States tabThe Factory States tab shows information about the current state of the connectionfactory. The tool bar at the top of the tab contains two groups of icons:• The icons on the left side of the tab's toolbar let you switch the view between a piechart, line chart, table, or diagram format; provide a shortcut that opens theStatistics Preferences tab; and let you toggle the display of the chart legend on oroff.• The icons on the right side of the tab's toolbar let you switch the display betweenaggregate inbound and outbound information.The information shown on the Factory States tab includes the following information:• not_exist: Indicates a Connectors (J2EE Connector Architecture) connectionfactory that in Borland Enterprise Server begins and ends its life cycle in this state.A newly created bean is in this state immediately after creation and before acontext is called on it. Note that Borland Enterprise Server uses the finalized stateconnection factories that once existed, but have left the Connector Container.• set_context: A newly creatconnection factory instance, upon which the ConnectorContainer is calling setContext() method, is in this state. The connection factorymoves into READY state after this (setContext()) call is over.• ready: This state corresponds to the ”method ready” state in the EJB specification fora connectionfactory. A connectionfactory is in this state to serve a method.• tx_ready: Indicates a connectionfactory that is associated with a transaction.Transaction association is set on a connectionfactory by the application.3-34 User’ s Guide

Partition Services• half_completed: Indicates a connectionfactory that is associated with a transactionis in tx_ready state. The connectionfactory is in this state after it has received abeforeCompletion callback from the transaction in which it has been participating.After the connectionfactory receives the afterCompletion callback, theconnectionfactory moves back to the ready state.• pooled: Indicates a connectionfactory instance that has been cached.• killed: Indicates a connectionfactory instance that was discarded as a result ofsystem exception. Factories in this state are usually discarded.• unreferenced: Indicates a connectionfactory that has been removed from thecontainer. Note that factories in this state are still consuming memory untilgarbage collection takes place (finalized).• finalized: Indicates the state of a connectionfactory after garbage collection hasreclaimed the memory used by the connectionfactory instance.Web Container propertiesNoteNoteThe following additional properties appear on the General tab for the Web Containerservice:• Enable Naming: When set to true (the default), tells the Tomcat service to use theJNDI (Java Naming and Directory Interface) implementation used by Tomcat 4 torepresent the default JNDI naming context provided to Web applications.• Debug: When set to true, tells the Tomcat Service to run with debug informationenabled. The default is false.For more detailed information on all of the Web Container properties, refer to theTomcat documentation located in the Borland Enterprise Server doc directory(install_dir/doc/tomcat).Web Container Server Statistics tabEach row on the Server Statistics tab represents a single servlet (or JSP) and thecolumns are attributes of the servlet.It is possible to have multiple servlets with the same name since a servlet must livewithin a Context (or Web application), which runs beneath a Host, which in turnruns within a Service. These levels of definition allow for servlets of the same name tocoexist, as long as they reside in a different Service/Host/Context.The columns on the Server Statistics tab are described below:• Name: The name of the servlet.• Service: The Service in which the servlet resides (specified by the protocol whichis used to communicate with that service, either HTTP or IIOP).• Host: The name of the Host on which the servlet runs.• Context: The name of the Web applications in which the servlet resides which isspecified by the path component of the URL used to access this application.The Servers view 3-35

Partition Services• Servlet Class or JSP File: The actual name of the class or file which implementsthe servlet.• # Hits: The total number of times the servlet has been accessed since the webcontainer was last started.• Hit Rate: The average number of times per minute that the servlet has beenaccessed. By default, this average is maintained for the 60 minute period beforeviewing or refreshing the Server Statistics tab. Activity which took place morethan 60 minutes before viewing this panel is not reflected in the average shown.• Response Time: The average number (in milliseconds) that the servlet took toprocess requests. By default, this average is maintained for the 60 minute periodbefore viewing or refreshing the Server Statistics tab. Activity which took placemore than 60 minutes before viewing this panel is not reflected in the averageshown.• Loaded: Indicated if the servlet has actually been loaded into the web container. Aservlet is loaded only when it is first accessed, unless it has been defined to theweb container as ”load on startup”.• Load Order: For ”load on startup” servlets, this number represents the relativeorder in which the web container should load the particular servlet. All servletswhose load order is ”1” are loaded before those with a load order of ”2”, and soforth. For non-”load on startup” servlets, this is shown as -1.• Last Accessed: The time when this servlet was last accessed. The value N/Aindicates a servlet has not been accessed since the web container last started.NoteConfiguring Web Container propertiesTo configure the Web Container properties:1 Switch to the Servers view in the Management Console and select the WebContainer node in the tree.2 Right-click on the Web Container node, and choose Configure.3 When you have completed your changes on the Configure Web Container dialogbox, choose OK.For detailed descriptions of the properties on the Configure Web Container dialogbox, click the Help button.By default, the Web container hosts the HTTP and the IIOP (Internet Inter-ORBProtocol) services with properties on the following tabs:• Engine tab• Host tab• Connector tabEngine tabThe following properties appear on the Engine tab:• Name: Specifies the name of the engine.3-36 User’ s Guide

Partition ServicesNote• DefaultHost: Specifies the name of the host to which requests will be directed ifthe requested host is unknown. The default is localhost.• ClassName: Specifies the Java class name that implements theorg.apache.catalina.Engine interface.• AppBase: Specifies the application root for the service which can be an absolutepath, a relative path, or a URL to the directory from which the service isautomatically deployed.• Debug: Specifies the detail level of debugging information that the enginegenerates, where 0 indicates none. The default is 0.The following elements appear on the Engine tab:• DefaultContext: Sets default configuration properties for a Web application.• Logger: Lets you customize the Tomcat logging system in which you can specifywhat data is generated and where it s stored.• Realm: Provides authorization and authentication services for a Web-application.• Listener: Lets you write an event processor that can send a notification whencertain request events occur.For additional information on these properties and elements, see the Tomcatdocumentation located in the Borland Enterprise Server doc directory (install_dir/doc/tomcat).Host tabThe following additional elements appear on the Host tab:• Name: Specifies the name of the engine.• AppBase: Specifies the application root for the service which can be an absolutepath, a relative path, or a URL to the directory from which the service isautomatically deployed.• Debug: Specifies the detail level of debugging information that the servicegenerates, where 0 indicates none. The default is 0.The following elements appear on the Host tab:• Contexts: Describes the Web application that enables you to use settings otherthan the default attributes for a Context. The Context element represents a webapplication, which is run within a particular virtual host. Each web application isbased on a Web Application Archive (WAR) file, or a corresponding directorycontaining the corresponding unpacked contents.• DefaultContext: Sets the to default configuration properties for a new Webapplication.• Valves: Lets you customize the processing of a request to a Web application byallowing you to insert your own processing logic into the request handlingprocedures of the Tomcat kernel.The Servers view 3-37

Partition ServicesNote• Logger: Lets you customize the Tomcat logging system in which you can specifywhat data is generated and where it s stored.• Listener: Lets you write an event processor that can send a notification whencertain request events occur.For additional information on these properties and elements, see the Tomcatdocumentation located in the Borland Enterprise Server doc directory (install_dir/doc/tomcat).Click the Ellipsis (...) button beneath the Properties button to examine the followingadditional properties for the localhost Contexts element.• Path: Specifies the context path of the server engine which is matched against thebeginning of each URI request received.• DocBase: The Document Base (also known as the Context Root) directory for theengine. It can be an absolute path name for the directory or a WAR file, or a pathname that is relative to the appBase directory of the owning Host.• Reloadable: If true, automatically reload the engine if it has been changed. Thisfeature is very useful during application development, but it requires significantruntime overhead and is not recommended for use on deployed productionapplications.• Debug: Specifies the detail level of the debugging information that is generated,where 0 indicates none. The default is 0.Connector tabThe following properties appear on the Connector tab:• ClassName: Specifies the Java class name that implements theorg.apache.catalina.connector interface.• Port: Specifies the port number where the HTTP or IIOP connector listens.• MinProcessors: Specifies the minimum number of processor threads to be createdwhen the connector is started. For the HTTP connector, the default is 5. For theIIOP service, the default is 0 (null) which tells Borland Enterprise Server to createno threads on startup.• MaxProcessors: Specifies the maximum number of processor threads supportedby the connector. For the HTTP connector, the default is 75. For the IIOP service,the default is 0 which tells Borland Enterprise Server to set no limit to the numberof processor threads that can be created.• EanbleLookups: Specifies if calls to request.getRemoteHost() perform DNS lookupsin order to return the actual host name of the remote client. If set to false, theConnector skips the DNS lookup and returns the IP address in string form(thereby improving performance). By default, DNS lookups are enabled.• Redirect port: If the Connector is supporting non-SSL requests and a request isreceived for which a matching requires SSL transport,the request is automatically redirected to the port number specified here.3-38 User’ s Guide

Shared Services propertiesNote• Redirect port: If the Connector is supporting non-SSL requests and a request isreceived for which a matching requires SSL transport,the request is automatically redirected to the port number specified here.• Redirect port: If the Connector is supporting non-SSL requests and a request isreceived for which a matching requires SSL transport, therequest is automatically redirected to the port number specified for this attribute.• Secure: If set to true, calls to request.isSecure() return true for requests received bythe Connector (you would want this on an SSL Connector). The default is false.• ProxyPort: If the Connector is being used in a proxy configuration, use thisattribute to specify the server port to be returned for calls torequest.getServerPort().• AcceptCount: Sets the maximum queue length for incoming connection requestswhen all possible request processing threads are in use. Anyrequests received when the queue is full will be refused. The default is 10.• Debug: Specifies the detail level of the debugging information that is generated,where 0 indicates none. The default is 0.• AppBase: Specifies the Application Base directory for the virtual host.• Scheme: Specifies the protocol you wish to have returned by calls torequest.getScheme(). For example, specify https for an SSL Connector. The default ishttp.• Name in OSAgent: Specifies the name that identifies the HTTP or IIOP connectorto the Smart Agent.The following elements are available on the Connector tab:• Factories: Returns a SSL (secure socket layer) socket for use by the HTTPSConnector to allow multiple SSL implementations to be used with the HTTPSconnector.• Listener: Lets you write an event processor that can send a notification whencertain request events occur.For additional information on these properties and elements, see the Tomcatdocumentation located in the Borland Enterprise Server doc directory (install_dir/doc/tomcat).Shared Services propertiesThe following sections describe the properties for the shared services which include:• 2PC Transaction Service• Apache 2.0• SonicMQ Broker• Smart AgentThe Servers view 3-39

Shared Services properties2PC Transaction Service propertiesThe following additional properties appear on the General tab for the 2PCTransaction Service:• Name: Specifies the name of the ITS Transaction Service instance used whenregistering its interface with the Smart Agent. The default is _ots.• Default transaction timeout: Sets the default transaction timeout value (inseconds) for the selected ITS Transaction Service instance. If not set, the default is600 seconds.• Default max transaction timeout: Sets the maximum allowed transaction timeoutvalue (in seconds) for the selected ITS Transaction Service instance. If not set, thedefault is 3600 seconds.• Log sleep: Specifies how long a transaction waits (in milliseconds) beforereturning from a synchronous log write operation. The default value is 0. Formulti-threaded environments with less than five concurrent transactions, thisdefault value is recommended. For multithreaded environments with five or moreconcurrent transactions, a value of 10 (ms) is recommended. If the number ofconcurrent transactions is considerably higher, a value greater than 10 (ms) shouldbe considered. Higher values increase throughput in high concurrency situationsat the expense of individual thread latency.• Log cache: Specifies the size of the log cache (in kilobytes). The default is 64 KB. Ifthe cache size is too small, an increased number of disk flushes are forced. Formost environments, the default value is suitable.• Purge old transaction records: Determines if transaction records will be purgedfrom the log:• False: (the default) specifies that existing transaction records will not be purgedfrom the log.• True: specifies that existing transaction records from previous invocations of thetransaction manager will be purged from the log. When set to true, all liverecords for the previous run of this instance of the ITS Transaction Service areforgotten (such as records for transactions that are pending completion).Additionally, setting this property to true enables you to change the directorylocation of the Transaction Service log when you restart the Transaction Service.To configure the 2PC Transaction Service:1 Switch to the Servers view in the Management Console and select the 2PCTransaction Service node in the tree.2 Right-click on the 2PC Transaction Service node, and choose Configure.3 When you have completed your changes on the Configure 2PC TransactionService dialog box, choose OK.3-40 User’ s Guide

Shared Services propertiesApache propertiesThe following additional property appears on the General tab for the Apache service:• Enable IIOP connector verbose output: When set to true, specifies that IIOPrequests will generate the logging of verbose information in the Apache log. Thedefault is false.Smart Agent propertiesThe following additional property appears on the General tab for the Smart Agentservice:• Enable verbose output: When set to true, tells the Smart Agent to provideinformation and diagnostic messages during execution. The default is false.Windows: On a Windows system, the verbose output is written to a log file stored atinstall_dir\var\servers\server name\adm\log\osagent.log or to the directory specifiedby the VBROKER_ADM environment variable. You an also use the OSAGENT_LOG_DIRenvironment variable to specify a different directory in which to store the log file.UNIX: On a UNIX platform, the verbose output is sent to the event log usingstandard stdout.For more information, see "Using the Smart Agent" in the VisiBroker Developer'sGuide.SonicMQ Broker propertiesThe following additional properties appear on the General tab for the SonicMQBroker service:• User: Specifies the username (default is ”Administrator”) used by the BorlandEnterprise Server to manage the SonicMQ broker. If security is enabled, the usermust be a member of the Administrator group. Otherwise, this property left empty.• Key: Specifies the security key for the Management port connection.• Encrypted Key: Specifies the encrypted key for the Management port connection.• Initialization File: Specifies the file location path to the SonicMQ broker.ini filethat used by the broker process. The default is /SonicMQ/broker.ini.• Admin Broker: Specifies the host port management connection URL used by theBorland Enterprise Server to locate the SonicMQ broker. The default islocalhost:2506.To configure SonicMQ properties:1 Switch to the Servers view in the Management Console and select the SonicMQnode in the tree.2 Right-click on the SonicMQ node, and choose Configure.The Servers view 3-41

Shared Services propertiesNote3 When you have completed your changes on the Configure SonicMQ dialog box,choose OK.For detailed descriptions of the properties on the Configure SonicMQ dialog box,click the Help button.3-42 User’ s Guide

Chapter4Chapter4The InstallationsviewWarningImportantUse the Installations view in the Borland Management Console to view and edit theconfiguration and property files of a server installed on the same machine as theBorland Management Server Console.Be sure to shut down the server before editing any of its configuration or propertyfiles. Otherwise, your changes may be lost and undesired results in server behaviormay occur.The Installations view also lets you perform the following actions on a serverinstalled on the same machine as the Borland Management Console:• start a server• update the ports associated with a server• view the log files associated with a serverThe Installations view contains the following areas:• An expandable and collapsible tree browser that shows the servers, services,partitions, and modules installed on the same machine as the BorlandManagement Console. To view or modify an object in the tree, navigate to it byexpanding its icon (node). If the object in the tree contains other objects, you canalso double-click the icons to expand the view.• The Borland Management Console opens a pane beneath the tree when itdiscovers associated configuration, property, security configuration, or log filesfor an object selected in the tree.• The window on the right displays and lets you edit the contents of a selected file.By default, the Borland Management Console displays the first file listed for thenode selected in the tree.For documentation updates, go to www.borland.com/techpubs/bes.The Installations view 4-1

Context menu commands in the Installations viewContext menu commands in the Installations viewIn addition to the commands on the Borland Management Console main menu, othercommands are available from a context menu (right-click) in the Installations viewwhen you select a node in the tree. The commands that are available from the contextmenu vary depending on the type of node that is selected.The following table shows the context menu commands (right-click) you can use onthe tree in the Installations view.Table 4.1CommandAdd InstallationStartRemoveUpdate PortsContext Menu CommandsDescriptionInstall a server on the same machine where the Borland Management Consoleis installed. This command is only available for the Installations node.Start a server installed on the same machine as the Borland ManagementConsole. This command is only available for server nodes.Unisntall Borland Enterprise Server. This command is only available for theBES node.Invokes the Port Configuration Wizard that streamlines the process ofchanging the port numbers that a server listens to for User and Managementfunctions.Editing files in the Installations viewTo edit a file in the Installations view:1 Use the tree in the Installations view to navigate to the node that represents thedesired server, partition, service, or module.2 Choose one of the tabs beneath the editor window to display one of the followingtypes of configuration files (the tabs that are available vary depending on the nodeselected in the tree):• Property Files• Configuration Files• Security Files• Log Files3 Make your changes in the Edit pane (see “Console File Editor context menucommands” on page 2-11), then click Apply Changes to save them when you aredone.The Installations view 4-2

Chapter5Chapter5The ClustersViewImportantThe Clusters View enables you to create new instances of Borland Enterprise Serverson selected hosts in your network, cluster them, and then associate them with anApache, JDataStore, or SonicMQ instance. It also allows you to create new instancesof these on selected hosts if none exist. A cluster is a group of identical servers thathas a single representation in the Clusters View tree. You manage several servers atonce as though they were a single entity. Managed resources (servers, Apacheinstances, and so forth) are also under active management. The Borland ManagementService automatically detects when a managed resource fails and re-starts it,enforcing dependency rules as well. Resources that fail are started in the properorder with regard to their dependencies.To start the Clusters View, click the ”Clusters” button on the left of the ManagementConsole.For documentation updates, go to http://www.borland.com/techpubs/bes.What is the Borland Management Service?The Borland Management Service encompasses a set of Management Agents whichcommunicate with a Management Hub. All Editions of the Borland Enterprise Serverare manageable out-of-the-box through their Management Agents. Any BorlandEnterprise Server on your system is manageable from the Hub. The Hub is installedon a single host in your network from which you carry out management tasks suchas clustering.The Clusters View 5-1

What is the Borland Management Service?The Management AgentTo start the Management Agent, use one of the following methods:• Windows: Choose Start|Programs|Borland Enterprise Server|BorlandManagement Agent.• UNIX: Open a command shell and enter the following command:bmsagentManagement Agent port numbers are assigned at installation time. (See theInstallation Guide for details on installing Management Agents.) Servers that aremanaged from the Hub must be assigned the same Management Agent port number.This is the port that will be used for discovery and communication between managedservers and the Hub. You can see the Management Agent's port in the lower right ofthe Management Console. You can change this port from any installation by rightclickingthe port number in its Management ConsoleFigure 5.1Management Agent port.Once installed, the Management Agent takes care of communicating with the Hub,allowing you to deploy modules, start services, and create new instances of Apache,JDataStore, and SonicMQ.The Management HubTo start the Management Hub, use one of the following methods:• Windows: Choose Start|Programs|Borland Enterprise Server|BorlandManagement Hub.• UNIX: Open a command shell and enter the following command:bmsserverThe Management Hub is installed on a single host in your network and shares aManagement Agent port number with the servers it manages. The Management Hubincludes a repository - a database which stores information about managed services sothat failover and recovery are easily implemented. The repository also keeps track oflogical groups of services that you define as clusters, as well as the modules deployedto those clusters.For example, you can use the Clusters View to define a cluster and then add serversto it. When you add a server, the Management Hub examines the repository forinformation about its cluster's services and creates those services on the addedserver. Once those services are installed, the Management Hub retrieves the requiredmodules from its repository and deploys them to the new server. If a server fails, itsmodules and services are easily retrieved from the repository and re-started.5-2 User’ s Guide

Using the Clusters ViewBorland recommends you install the Management Hub on a host whose sole task isto perform management of other hosts. This is not a requirement for use of the Hub,but is considered a ”best practice.”Using the Clusters ViewThe Clusters View shows four sets of manageable resources. These are:• Clusters: logical groupings of identical servers that appear to clients as singleentities• Apache Web Servers: instances of the Apache Web Server which can be associatedwith clusters as their front end• JDataStore instances: instances of JDataStore, Borland's all-Java database. TheBorland Management Service can not manage other databases at this time.• SonicMQ instances: instances of SonicMQ which can be associated with clustersto provide their messaging servicesFigure 5.2Top-level nodes.When you create a cluster, you use the Cluster Wizard to define the services it willprovide and the modules it will host. Any of the managed Apaches, JDataStores, andSonicMQs can then be associated with a cluster. Once you have defined the logicalconstruction of the cluster, you can then add servers that will actually perform thecluster's work and host its modules. The Management Hub takes care of creating theproper server instances, configuring the partitions, and deploying the modules.First let's examine how to create managed Apaches, JDataStores, and SonicMQs.Then we'll look at how to define a cluster and associate it with these additionalresources with the Cluster Wizard. Finally, we'll add servers to the cluster.Creating a Managed Apache Web ServerTo create a Managed Apache Web Server, right-click the Managed Apache WebServers node in the tree and select New Apache. The ”Create New Managed ApacheWeb Server Wizard” appears.The Clusters View 5-3

Using the Clusters ViewFigure 5.3Apache WizardThe Management Console queries its environment and detects running ManagementAgents on the local subnet. You select which agent will host the Apache instancefrom the drop-down list. If no hosts are running Management Agents at the portspecified in the lower-right of the Management Console, you will see the error ”noagents found.” Make sure you have a running Management Agent at the proper porton at least one host in your subnet.Next, enter a name for your Apache instance. When you are finished, click the Finishbutton. The Apache instance is initialized on the host you chose. The new ApacheWeb Server appears in the tree.Figure 5.4New Apache instanceYour new Apache instance begins its life in an idle state. To start it, simply Rightclickits representation in the tree and select Start from the context menu. You canreconfigure this Apache instance (to change it's Smart Agent port, for example), byRight-clicking its representation and selecting Configure from the context menu. Thisre-launches the Create New Apache Web Server Wizard in an edit mode. You mayedit selected fields and click Finish to save your changes.You can view the properties of an existing Apache instance at any time byhighlighting it in the tree. Its properties appear in the Content Pane.5-4 User’ s Guide

Using the Clusters ViewFigure 5.5Viewing Apache informationYou can change some of these values by re-configuring the Apache instance. Othersare available through the Installations View on its host.Creating a Managed JDataStore DatabaseTo create a Managed JDataStore Database, right-click the Managed JDataStoreDatabases node in the tree and select New JDataStore. The ”Create New JDataStoreProcess” appears.Figure 5.6JDataStore WizardThe Management Console queries its environment and detects running ManagementAgents on the same management port. You select which agent will host theJDataStore process from the drop-down list. If no hosts are running ManagementAgents at the port specified in the lower-right of the Management Console, you willThe Clusters View 5-5

Using the Clusters Viewsee the error ”no agents found.” Make sure you have a running Management Agentat the proper port on at least one host in your subnet.Next, enter a name for your JDataStore process. You will then have to enter a port touse to communicate with the JDataStore. This is a port on its host that the JDataStoreprocess uses to listen for queries. When you have completed entering the necessaryinformation, click Finish. The JDataStore is instantiated on the host you chose. Thenew JDataStore process appears in the tree.Figure 5.7New JDataStore processLike Apache instances, you can view the configuration information for your newJDataStore process by clicking its representation in the tree. Information on theJDataStore appears in the Content Pane.Figure 5.8Viewing JDataStore informationCreating a Managed SonicMQ Messaging ServiceFollow the on-screen instructions for creating a Managed SonicMQ MessagingService. For details on the specifics of your SonicMQ Messaging Service, consult theSonicMQ documentation bundled with your installation of Borland EnterpriseServer.5-6 User’ s Guide

Creating ClustersFigure 5.9SonicMQ WizardWhen you are done, click Finish.Creating ClustersThe Cluster Wizard allows you to define a logical set of services and application logicthat are deployed on several hosts acting in concert. The Management Hub stores allthe necessary service and module parameters in its repository and uses thisinformation to configure the individual servers that will host them. Once you havedefined the services and modules the cluster will host, you then distribute theseservices and modules to individual servers by using the Add Server Wizard. TheBorland Management Service takes responsibility for configuring the Partitions thatwill run on the servers you add, and then will deploy all the necessary modules tothose Partitions. The servers can then fail-over to each other, and scaling is as easy asrunning the Add Server Wizard whenever you need to increase the availability orfault-tolerance of your system.Creating a Cluster Definition with the Cluster WizardIn the Borland Enterprise Server, clusters are formed at the Partition-level. That is,when you create a cluster, you are actually creating a set of Partitions from differentservers that act as one. A single server can have several Partitions participating inmultiple clusters. When you add a server to a cluster, you are actually selecting aserver upon which a new Partition is created. This Partition implements the clusterdefinition you provide in the Cluster Wizard. Defining a Cluster with the BorlandEnterprise Server involves the following steps:1 Naming the cluster and providing a description for it.The Clusters View 5-7

Creating Clusters2 Defining the cluster's services. These are the Partition services that will beavailable to the deployed modules in the cluster's Partitions.3 Optionally choosing an enterprise back-end or database. You supply theappropriate Data Archive (DAR) that defines the cluster's datasources.4 Optionally choosing an Apache web server to service the cluster.5 Optionally choosing a SonicMQ messaging service to service the cluster.6 Selecting the modules to be deployed to the cluster.Step OneThe Cluster Wizard walks you through the creating of a cluster definition fromscratch. To start the Cluster Wizard, right click on the ”Managed Clusters” node inthe tree and select New Cluster. The Cluster Wizard Step 1 appears.Figure 5.10 Cluster Wizard step 1First, enter a name for your cluster and, if you desire, a brief, humorous description.Click Next. Step Two appears.5-8 User’ s Guide

Creating ClustersStep TwoFigure 5.11 Cluster Wizard step 2Next, select the services you want to enable on the cluster. These services are inaddition to those already present by default — the Naming Service and the SessionService. Unchecking any of these boxes does not prevent you from going back andchanging them later.You also need to specify a Smart Agent port that this cluster will use to communicate.If you already have an existing Apache instance and would like to use it with thiscluster, use its port number here. Or, you may provide a new one and allow theWizard to re-configure it for you in Step Four. Finally, you need to provide themaximum number of Smart Agents to use per subnet. Too many Smart Agents canclog the communication channels between Partitions, but too few could lead toinadequate failover. The Borland Management Service starts and stops these SmartAgents as needed. By default, it will never create more Smart Agent instances thanthere are servers in the cluster.Once you have completed this step, click Next. Step Three appears.The Clusters View 5-9

Creating ClustersStep ThreeFigure 5.12 Cluster Wizard step 3In Step Three you define the enterprise back-end for your cluster. There are fourchoices available to you:• Use an existing external database: If you are using an existing database such asOracle, you select the Data Archive (DAR) that defines its connection factory classand datasource. You can browse for a DAR file by clicking the Browse... button.The Wizard then scans the DAR for its datasource definitions, which are thendisplayed in the drop-down list. Select the datasource you wish to use for theappropriate database. DARs are fully-documented in ”Connecting to Resourceswith Borland Enterprise Server” in the Developer's Guide. The DAR you selectwill be deployed to each server in the cluster.• Use an existing managed JDataStore process: If you have already created aManaged JDataStore process using the JDataStore Wizard, right-click theManaged JDataStore Databases node in the tree and select New JDataStore. The”Create New JDataStore Process” appears., you can simply select it from the dropdownlist. You may need to refresh the list by clicking the Refresh button if youcreated the managed JDataStore just before starting the Cluster Wizard, or if youlaunched the JDataStore Wizard from within the Cluster Wizard.• Use the Server Tools to create a new DAR: You may also create a new DAR byclicking the Launch DDEditor button. This starts the DDEditor (see Chapter 9,“Using the Deployment Descriptor Editor”) which walks you through the creatingof the jndi-definitions.xml file that is the heart of the DAR. You can also loadthe default-resources.dar default file and edit its datasources to suit yourenvironment.• Create a new Managed JDataStore Process: You can also create a new managedJDataStore process by launching the JDataStore Wizard: right-click the ManagedJDataStore Databases node in the tree and select New JDataStore. The ”CreateNew JDataStore Process” appears. described above. Click the Launch JDataStore5-10 User’ s Guide

Creating ClustersWizard button to do this. A new managed JDataStore will be created and appearin its appropriate place in the tree.Once you have made your selection and accomplished any related tasks, click Next.Step Four appears.Step FourFigure 5.13 Cluster Wizard step 4In Step Four you define your cluster's front-end. This is an optional step; your clustermay not need to connect to an Apache server. If your cluster requires the Apachefront-end, you have two choices to implement it:• Use an existing managed Apache web server: If you have already used theApache Wizard , to create a Managed Apache Web Server, right-click theManaged Apache Web Servers node in the tree and select New Apache. The”Create New Managed Apache Web Server Wizard” appears. to create a managedApache instance, check the box and choose the appropriate instance from the dropdown list. You may need to refresh the list if you created the managed Apacheinstance just before launching the Cluster Wizard or if you created a new managedApache from within the Cluster Wizard.• Create a new managed Apache web server: You can also create a new managedApache instance by clicking the Launch Apache Wizard button. Once you havecompleted the Wizard, you will be returned to Step Four. Click Refresh and selectyour new Apache from the drop-down list.Once you have completed this step, click Next. Step Five appears.The Clusters View 5-11

Creating ClustersStep FiveFigure 5.14 Cluster Wizard step 5In Step Five you can optionally select a SonicMQ messaging service to service yourcluster. As with the Apache web server instances, above, you have two choices:• Use an existing managed SonicMQ service: If you have already used theSonicMQ Wizard. Follow the on-screen instructions for creating a ManagedSonicMQ Messaging Service. For details on the specifics of your SonicMQMessaging Service, consult the SonicMQ documentation bundled with yourinstallation of Borland Enterprise Server. to create a managed SonicMQ service,check the box and choose the appropriate instance from the drop down list. Youmay need to refresh the list if you created the managed Sonic MQ service justbefore launching the Cluster Wizard or if you created a new managed SonicMQservice from within the Cluster Wizard.• Create a new managed SonicMQ service: You can also create a new managedSonicMQ service by clicking the Launch SonicMQ Wizard button. Once you havecompleted the Wizard, you will be returned to Step Four. Click Refresh and selectyour new SonicMQ service from the drop-down list.Once you have completed this step, click Next. Step Six appears.5-12 User’ s Guide

Creating ClustersStep SixFigure 5.15 Cluster Wizard step 6In the last step, you determine which modules you would like deployed to eachPartition that will be in your cluster. Since the Borland Management Service does notgenerate stubs at deployment time, you must make sure all the necessary stubs havebeen generated for your modules before you can add them to the modules list. If youare unsure if you have properly generated your stubs, launch the Stub Wizard byclicking its button and select its ”Create archive files for manual deployment” option.After you have run the Stub Wizard, save the modules. You can then add them to themodules list.To add a module, click the Add button and navigate to your module's location toselect it. To remove a module, highlight its representation in the list and click Remove.Once you have selected all your modules, click the Finish button. The modules aresaved in the Management Hub's repository for future deployment, and your clusterappears in the tree.The Clusters View 5-13

Creating ClustersFigure 5.16A new clusterEditing an existing Cluster DefinitionTo edit an existing cluster definition, right click its representation in the tree andselect ”Configure.” This re-launches the Cluster Wizard in an edit mode. Once youhave finished, your cluster will be reconfigured. The Borland Management Servicetakes care of any Partition re-starts and redeployment of modules. You can also lookat your cluster's representation in the tree and expand it to see which Partitions onwhich servers are hosting the cluster. You can then navigate to the Server View orInstallations View for those servers and configure the Partitions manually. Just makesure that whatever changes you make to one Partition, you make to all the Partitionsparticipating in the cluster.The Cluster in Action: Using the Add Server WizardOnce you have defined your cluster, it is time to create servers to host it. You cancreate a server on any host that has an installation of the Borland Enterprise Serverand is running a Management Agent. To add a server to a cluster, Right-click yourcluster in the tree and select ”Add New Server...” from the context menu. The AddServer Wizard appears.5-14 User’ s Guide

Creating ClustersFigure 5.17Add Server WizardSimply select a host running a Management Agent from the drop-down list. Thengive your server a name. When you are done, click Finish. The new server appears inthe tree under your cluster's name.Viewing Cluster InformationThe Navigation Pane shows the logical group of servers acting as a cluster under thename of your cluster definition. You can expand the tree and examine the Partitionsand services enabled within the server. Note that the individual servers are nameddifferently in the Clusters View than in the server view, with the server nameappended to the cluster name. Look at the figure below, where two servers,TheSilentOne and TheLoudOne, have been added to TheCluster.The Clusters View 5-15

Creating ClustersFigure 5.18Deployed cluster tree representationThe server called TheSilentOne appears as TheCluster_TheSilentOne in the tree. Inlarger tree layouts it can be difficult to tell where the parent nodes and the childnodes begin. This naming convention can help you navigate especially large clustertrees.Like in the Servers view, (see Chapter 3, “The Servers view”), you can Right-click theservices in the tree and start, stop, idle, and in some cases configure them. Once youstart a server or service, it also appears in the Server View for configuration. Besidethe functionality of the Wizards, the Cluster View merely allows a different way ofviewing your system, one whose focus is more an abstraction of the logical layout ofthe system.The Content Pane allows you to view your cluster's attributes and see a graphicallayout of its services. The Management Properties Tab shows you the properties ofthe ”managed” Partitions within your cluster. You can change these parameters byRight-clicking the cluster in the Navigation Pane and reconfiguring it. Just as usefulis the Cluster Graph Tab, which shows you a graphical representation of your cluster.It is also useful in determining which server in the cluster has been assigned theSmart Agent. The figure below shows a the cluster graph for the server configurationabove:5-16 User’ s Guide

Creating ClustersFigure 5.19Deployed cluster graphical representationEach Partition's (the ”managed” nodes) services are set up identically, hence they allpoint to identical services. The server called TheSilentOne (the first of the two to beadded to TheCluster) was assigned the Smart Agent.Understanding the State IconsIn the figures above, you no doubt noticed the icons next to the objects in the tree.These icons display information on the state of each object in the tree. If an object inthe tree is managed by the Borland Management Service, it has two icons. The firsticon shows the actual state of the object. The second icon shows its desired state.When an object is managed, the Borland Management Service alone maintains itsstate and tracks the object's dependencies. You must tell the Borland ManagementService what state you would like maintained. You do this by Right-clicking theobject in the tree and selecting one of the actions from the context menu.The Clusters View 5-17

Creating ClustersFigure 5.20Selecting desired state for an objectThe actions you can perform also set desired state on the object as follows:• Restart: stops the service and restarts it, sets the desired state of the object to”Running”• Start: starts the service and sets its desired state to ”Running”• Stop: stops the service and sets its desired state to ”Stopped”• Kill: stops the service and sets its desired state to ”Stopped”• Obey Dependencies: the service will start or stop when required by anotherservice dependent on the objectThe state legend is available in the Management Console under Management Console|Preferences. Click the State tab to see the legend.5-18 User’ s Guide

Start/Stop Dependencies in Borland Enterprise ServerFigure 5.21State icons legendThe Borland Management Service will automatically stop and start services in orderto maintain the desired state of the objects in the tree.Start/Stop Dependencies in Borland Enterprise ServerThe Borland Enterprise Server Management Console displays state icons for manyobjects in its Navigation Pane. One of these is the ”Obey Dependencies” icon.This icon is most closely associated with user-created clusters. When you create acluster, you create a logical framework of application resources that can be startedand stopped as a coherent whole, although the Partitions and BES Server instancesthat make them up may be on different machines. For example, a cluster's server treemay look like the following:The Clusters View 5-19

Start/Stop Dependencies in Borland Enterprise ServerFigure 5.22Example Clusters View tree representationYou'll note the cluster PetstoreCluster at the top of the tree. Every child node of thePetstoreCluster (and by extension the PetstoreCluster itself) is a managed object.Child nodes such as the PetstoreServer-001, the Apache Server ApacheOne, and theJDataStore and Sonic instances ”obey” the status of the PetstoreCluster. If thePetstoreCluster is supposed to be running, the Borland Management Service makessure that all its dependencies are running as well.The following diagram shows which components start and stop the others. This is animportant diagram, for it shows that you cannot simply assume that a managedobject's child-node is started and/or stopped by its parent.5-20 User’ s Guide

Start/Stop Dependencies in Borland Enterprise ServerFigure 5.23Starting and stopping of components by other componentsStarting Managed ObjectsThe blue arrows indicate start direction. When you start a cluster, it in turns issuesstart commands to the JDataStore, SonicMQ, and the Managed Apache domain,assuming these are necessary. The Apache domain (the Managed Apaches node inthe Clusters View), in turn, invokes the necessary Apache 2.0 service, which starts theBES Server instance necessary for it to run.At the same time, the cluster invokes a start command on the Smart Agents (osagent)and Partitions that make up the cluster's definition. These components start thenecessary BES Server instances necessary for them to run.The Clusters View 5-21

Start/Stop Dependencies in Borland Enterprise ServerFigure 5.24Starting managed objectsStopping Managed ObjectsThe red arrows indicate stop direction. When you stop a cluster, it in turns issuesstop commands to the JDataStore, SonicMQ, and the Managed Apache domain,assuming these are necessary. The Apache domain instructs its managed servers tostop, and those in turn terminate the Apache process associated with the cluster.At the same time, the cluster instructs its associated BES Server instances to stop, andthose in turn terminate the Smart Agent and Partition processes associated with thecluster.Figure 5.25Stopping managed objects5-22 User’ s Guide

Chapter6Chapter6Configuring security with the BorlandManagement ConsoleImportantYou can configure security settings using the Borland Enterprise Server ManagementConsole. Security is configured at the Partition-level, meaning that you mustconfigure security for each Partition running on each enterprise server. EachPartition can have its own authorization rolemap, authentication policies, and SSLsettings. You can use the Borland Enterprise Server Console to:• Set the logging level• Enable security and SSL protection• Set authorization rolemaps for use by the selected Partition• Set authentication policiesFor documentation updates, go to www.borland.com/techpubs/bes.Getting StartedNoteTo begin configuring security from the Console:1 Select the Servers view and expand the navigation tree to show the Partitionsrunning on your server, then select the Partition that you want to configure.2 Right-click the Partition's node in the tree, then select Configure to open theConfigure Partition dialog box.3 Select the Security Tab and check the Security enabled checkbox to enable security.You must enable security for the Partition before you can edit its securityproperties.4 If desired, click the Secure Transport (SSL) Enabled checkbox to enable SSLsupport for your Partition.Configuring security with the Borland Management Console 6-1

Setting the logging levelFigure 6.1Configure Partitions Security tabSetting the logging levelYou set the logging level for check box all security-related interactions by selecting avalue from the Logging Level drop-down list. The options are:• 4 - Warning: warning conditions only• 5 - Notice: conditions that are not error conditions, but which can require specialhandling• 6 - Info: informational logging only• 7 - Debug: this setting is used when contacting Borland Developer Support isnecessary. If you are having problems with security, Borland Developer Supportcan have you select this value in order to troubleshoot your system. It provides noadditional logging capabilities without Borland Developer Support's assistance.Configuring AuthenticationAuthentication settings are stored in authentication configuration files. To edit theassociated authentication configuration file:1 Click the Authentication button on the Security tab of the Configure Partitiondialog box.2 Make your changes in the Authentication Settings edit window. The edit windowfunctions much like a standard text-editor. See Console File Editor context menu6-2 User’ s Guide

Configuring Authorizationcommands for descriptions of the available editing commands. From here you canedit the LoginModules used for the various Partition realms to be supported.Information on configuring these realms is provided in the Borland EnterpriseServer Developer's Guide in the Authentication Chapter which provides detailedinformation on the structure and grammar of configuring authentication realmsand policies.3 When you have finished editing the authentication settings, click OK to save yourchanges.Configuring AuthorizationNoteAuthorization settings are stored in configuration files called rolemaps. The settingsin a rolemap file define a security domain within which specified authorizationcriteria applies to all services, modules, and resources in a given Partition. To edit arolemap file associated with the selected Partition:1 Click the Authorization button on the Security tab of the Configure Partitiondialog box to open the Security Domain Browser.2 Expand the Security Domain Browser tree to the node of a specific rolemap file orto a specific rolemap property that you want to edit.3 Make your changes in the edit window on the right side of the Security DomainBrowser. The edit window functions much like a standard text-editor and lets youedit the rolemap file for your Partition. See Console File Editor context menucommands for descriptions of the available editing commands.Although you can expand the nodes in the tree to view individual roles and rules,you can only make edits in the Security Domain Browser edit window when arolemap node is selected. To edit an individual rules, see Editing an authorizationrule.Configuring security with the Borland Management Console 6-3

Configuring AuthorizationFigure 6.2Security Domain Browser4 Make your changes, then click Verify to validate the syntax. If errors occur, theyappear in the bottom pane.5 When you are done, choose Save from the Security Domain Browser File menu.Additional instructions on how to configure the rolemap file for your variousauthorization domains are provided in the Authorization section of the Developer'sGuide which provides detailed information on the structure and grammar ofconfiguring authorization domains and rolemaps.Creating a new authorization rolemap fileTo create a new authorization rolemap file:1 Right-click on the Security Domains node in the Security Domain Browser treeand choose New Domain.2 Enter a new name for your rolemap file in the Create New Domain dialog box andclick OK.Cloning an authorization rolemap fileTo clone a rolemap file:1 Expand the mn Security Domain Browser tree to the node of a specific rolemapthat you want to clone.2 Right-click its node and choose Clone Security Domain.3 Enter a new name for the rolemap file in the Clone Security Domain dialog boxand click OK.6-4 User’ s Guide

Configuring Authorization4 Select the node of the cloned rolemap file in the tree and make any changes in theedit pane of the Security Domain Browser. Be sure to follow the grammarspecified in Authorization in the Developer's Guide.5 When you are finished, click OK to save your changes.Creating a new authorization roleA rolemap file contains a set of roles that each comprise a list of rules that must besatisfied to be authorized to use a particular resource. To create a new authorizationrole:1 Right-click on a rolemap node in the Security Domain Browser tree and chooseNew Role.2 Enter a new name for your role file in the New Role dialog box and click OK.Creating an authorization ruleTo create a new authorization rule:1 Expand the mn Security Domain Browser tree to the node of a specific role thatyou want to modify.2 Right-click its node and choose New Rule to open the Rolemap Rule editor.Figure 6.3Rolemap Rule editor3 Check the Match all conditions below exactly and nothing else checkbox if youwant to the rule to exclude all other rolemap conditions (assertions). Otherwise,clear this checkbox if you want any additional conditions to apply to the rule. Fordetailed information on rolemap syntax and grammar, see Authorization in theDeveloper's Guide.Configuring security with the Borland Management Console 6-5

Advanced Security ConfigurationNote4 Click the More Conditions button to supply additional assertions or click theFewer Conditions button top remove rules.To disable a condition without removing the conditions that follow it, you canblank out the left most field for a specific condition or edit the file manually.5 Click Preview to examine the complete rule syntax in the field at the top of theeditor.6 When you have finished, click OK to save your edits.Editing an authorization ruleTo edit an authorization rule:1 Expand the Security Domain Browser tree and select the node of a specific rulethat you want to modify.2 Click the Edit button on the bottom of the right pane to open the Rolemap Ruleeditor.Creating an authorization role referenceA role reference lets you apply the same rules from existing role to the current role.To create a role reference:1 Right-click on the role node in the Security Domain Browser tree and choose NewRole Reference.2 Enter a new name for your rolemap file in the New Role Reference dialog box andclick OK.The next time you collapse and expand the role node, the Referenced Role nodeappears below the role.Advanced Security ConfigurationYou may need to set VisiBroker properties to properly configure your securityimplementation Security Configuration in the Borland Enterprise Server Developer'sGuide for the steps necessary to fully configure security for your enterprise server.Some of the VisiBroker security settings can be performed from the command-line orprogrammatically using APIs. Most can be performed by editing the VisiBrokerconfiguration file and setting the appropriate properties.To edit VisiBroker Properties using the Console:1 Select the Servers view and expand the tree to show the Partitions running on yourserver, and select the Partition that want to configure.2 Right-click its node in the tree and select Configure from the context menu to openthe Configure Partition dialog box.6-6 User’ s Guide

Advanced Security Configuration3 Click the VisiBroker tab.Figure 6.4Configure Partitions VisiBroker tab4 Click the Advanced button. The VisiBroker Properties edit window appears.Note5 Use this window as you would a text-editor. See Console File Editor context menucommands for descriptions of the available editing commands.Take special care in editing this file.6 When you are finished, click OK to save your changes.Configuring security with the Borland Management Console 6-7

6-8 User’ s Guide

Chapter7Chapter7WizardsImportantThis section describes how to use the Borland Enterprise Server Wizards that guideyou through such actions as stub generation, deployment of modules, merging ofmodules and libraries, JAR compression and patch application, verification, andmigration of modules from J2EE 1.2 to J2EE 1.3.For documentation updates, go to www.borland.com/techpubs/bes.Using the Borland Enterprise Server wizardsThe following wizards are available on the Wizards menu on the Console:• Deployment Wizard – see the “Deployment Wizard” on page 7-3• Cluster Wizard – see Chapter 5, “The Clusters View”• Verify Wizard – see the “Verify Wizard” on page 7-9• XML Migration Wizard – see the “XML Migration Wizard” on page 7-10• Merge Wizard – see the “Merge Wizard” on page 7-6• Stub Generation Wizard – see the “Stub Generation Wizard” on page 7-12• Remove Stubs Wizard – see the “Remove Stubs Wizard” on page 7-16• Apply Patch Wizard – see the “Apply Patch Wizard” on page 7-17• JAR Wizard – see the “JAR Wizard” on page 7-17The Stub Generation wizards enable you to create stubs for client non-containerapplications, generate a single JAR file containing just generated stub classes andremove any stubs from existing JAR files. Each wizard guides you through a two stepprocess.You can use the J2EE Deployment wizard to deploy your J2EE archives. The wizardguides you through the process of deploying your files to one or more partitionsWizards 7-1

Deploying J2EE componentsNoteand/or Borland Enterprise Servers, or preparing a module for future deployment.Another deployment wizard enables you to generate JARs with all necessary stubssuitable for manual deployment to a server.The Merge Utilities allow you to merge a number of your modules to produce 1.1and/or 2.0 EJBs and to merge modules to produce 1.2 and/or 1.3 EARs. In addition,the Merge libraries task enables you to produce a library file from selected JAR files.The JAR Utilities consist of three wizards that allow you to compress, uncompress orapply patches to existing JAR files.The XML Migration wizard will automatically upgrade any J2EE 1.2 modules to J2EE1.3 modules and the reverse, from J2EE 1.3 to J2EE 1.2 modules.The XML migration process does not migrate Container Managed Persistence (CMP)1.1 to CMP 2.0.Prior to, or after a module is deployed, you can use the Deployment DescriptorEditor to change deployment information as desired. For example, you can use theeditor to specify or change the Transaction Policies and Security Roles for anenterprise bean. The Deployment Descriptor Editor can be accessed from theDeployment wizard.Additional wizardsIn addition to the wizards available from the Wizards menu, the Console also offersthe following wizards:• Add Server Wizard – see “The Cluster in Action: Using the Add Server Wizard”on page 5-14• Create New Managed Apache Web Server Wizard – see “Creating a ManagedApache Web Server” on page 5-3.• JDataStore – see “Creating a Managed JDataStore Database” on page 5-5• Registration Wizard – see “Registration Wizard” on page 7-17• Create New Managed SonicMQ Messaging Service – see “Creating a ManagedSonicMQ Messaging Service” on page 5-6• Export EJB as a Web Service Wizard – see “Export EJB as a Web Service Wizard”on page 7-18Deploying J2EE componentsIn the Borland Enterprise Server, deployment is the process of distributing andmaking available for use by clients, a set of J2EE modules. The Borland EnterpriseServer can deploy both standalone modules to servers as well as completeapplications (EARs). In addition to the standard J2EE modules, the BorlandEnterprise Server allows you to deploy library Jars to a server. A library JAR is anyJAR that you want placed on the server's classpath.7-2 User’ s Guide

The deployment processYou can install any number of J2EE modules on a server. You can deploy modules inthe following ways:• Using the Deployment wizard included with the Borland Enterprise ServerConsole. The following sections describe how to use the Deployment wizard todeploy these components.• Using the iastool command-line utilities. For more information, see Chapter 10,“iastool command-line utility”.• Using the commands in the EJB toolkit (EJBs only). For more information on theEJB toolkit, see the Borland Enterprise Server Developer's Guide.The deployment processThe deployment process involves four distinct phases:• Supplying runtime data• Stub generation• Verification• Installation and activationDeployment WizardThe Deployment wizard guides you through the process of deploying modules. Inaddition to deploying J2EE modules to a partition, you can create a JAR file suitablefor manual deployment. This wizard generates JAR files containing all of thenecessary stubs for a manual deployment to a server which is useful if you want tocreate a deployable JAR, but do not want to deploy it right away.Before you begin deployment, you need to supply the runtime data (such as the JNDIname of an EJB). This is stored in a Borland-specific XML file, the name of which isdependent upon the module type. For example, for EARs the Borland XML file iscalled application-borland.xml. This file needs to be created and stored within the J2EEmodule you want to deploy. The easiest way to do this is to open the J2EE moduleusing the DDEditor and fill in the missing XML information.To add one or more J2EE modules to a server:1 From the Wizards menu on the Console, select Deployment Wizard.2 On Step 1 of the Deployment Wizard, click Add to browse the directory tree andselect the module(s) to select the files to deploy to a container.Wizards 7-3

Deployment WizardFigure 7.1 Deployment Wizard: Step 13 On the Add J22EE module window, select the modules you want to add and clickOK. You can add as many files as you want. Once the files have been selected, theWizard displays an expandable tree browser that shows the module selections andtheir contents. (To remove a module, select its node icon in the tree and clickRemove.)4 Specify additional options:• Restart Partition on deploy. To deploy library Jars or RARs and add them tothe server's classpath, the server needs to be restarted. Check this option if youwant this action to occur as part of the deployment process.• Verify deployment descriptors. Verifies that supplied deployment descriptorsfor the added modules are correct.• Generate stubs. Stub generation is required so that modules are in a form thatthe server is expecting. For EJBs, this involves generating client and server-sidestubs.5 If you want supply additional information to generate stubs or verify thedeployment descriptors, click Advanced Options to open the AdvancedDeployment Options dialog box:• Use the Stub Generator tab to add classpath information and command linearguments for the java2iiop and javac compilers.7-4 User’ s Guide

Deployment WizardFigure 7.2Advanced Deployment Options Stub Generation tabNoteClick Edit to open the Classpath Editor where you can add an archive or specifythe location of any classpath dependencies. To remove a selection, select its iconand click Remove). Use the Arguments box to specify any command linearguments (click More Info to display Java2IIOP usage information).Stub generation is required so that modules are in a form that the server isexpecting. For EJBs, this process involves generating client and server-sidestubs. Since stubs in the server are generated from the Console and not on theserver, any classes that are needed during stub generation (that is, compile timedependencies of the Home and Remote interfaces of the beans within the EJB)will need to be available to the Console. By default, if you are deployingmultiple modules, then all modules are placed on the classpath of the stubgenerator. So, if your beans have references to beans in other Jars, a multipledeployment requires that you add the other Jars to the classpath. In addition,you can enter any arguments that may be needed by the file. Click the MoreInfo button for a detailed usage statement and consult the Borland EnterpriseServer Programmer's Reference for information about the Java2 IIOP tool.If you add a classpath here, remember that you must add the classpath on theserver-side too.• Use the Verifier tab to choose whether or not to verify that the deploymentdescriptors for the added modules are correct and, if so, to show all warnings(in addition to errors) and use pedantic or strict verification procedures toproduce warning messages related to the compliance of your J2EE moduleswith J2EE specifications.Figure 7.3Advanced Deployment Options Verify tabVerification helps you find exactly what information you need to specify.6 On Step 2 of the Deployment Wizard, choose to deploy the selected modules to aPartition or the Clusters View. Click Refresh List if the available Partitions orClusters on the server or servers have recently changed.Wizards 7-5

Merge WizardFigure 7.4 Deployment Wizard: Step 2Merge Wizard7 Click Finish to tell the Wizard to complete the deployment process. The wizardanalyzes the file(s) and displays the results in the Deploying Modules window.The modules are checked for validity and any errors or warnings encountered areshown. If the Partition you are deploying fails to load the module, errors willdisplay the Partition's Log tab.If one or more files have errors, you may want to take any of the following actions:• Stop the Deployment Wizard and use the DDEditor to fix the problem. For moreinformation, see the Chapter 9, “Using the Deployment Descriptor Editor”.• Use an IDE tool to fix the problem.These utilities produce Jars and EARs by merging your components and modules.The wizards analyze your EJB JAR and EAR file(s) and attempt to determine theminimal set of classes required by clients to access them. A JAR or EAR filecontaining the minimal set of classes is then produced. In addition, the mergelibraries wizard will produce a library file for your selected files.To assemble an application, the deployment descriptors must be edited for themodules to link dependencies between components in different archives. Alldependencies must be linked before deployment. For example, the description ofEJBs in a WAR file should match with their description in the EJB JAR file.If you are merging EJBs and want the wizard to try to match JNDI references withbean JNDI names in the deployment descriptor, select Convert EJB JNDI referencesto links where possible.In addition, if the JAR files contain EJB 1.1 deployment descriptors, they will beconsolidated into a single deployment descriptor.7-6 User’ s Guide

Merge WizardThe Merge Wizard lets you:• Merge modules to produce a 1.2 EAR• Merge modules to produce a 1.3 EAR• Merge librariesTo merge modules to produce an EJB client JAR files and J2EE EAR files:1 From the Wizards menu on the Console, select Merge Wizard.Figure 7.5 Merge Wizard2 Select the type of Module that you want to merge and the J2EE version of theresulting file, then click Next.3 Click Add to browse the directory tree and select the JAR or EAR file(s). You canadd as many files as you want.Wizards 7-7

Merge WizardFigure 7.6Merge Wizard module selection4 Select the modules that you to merge, then click OK. (If you want to remove one ormore files, highlight the file or files, then click Remove.)5 Click Next.6 Designate an output file from the merge process, either by entering a file name orbrowsing to a directory using the Browse button.Figure 7.7Merge Wizard Output Location7 Click Finish.7-8 User’ s Guide

Verify WizardVerify WizardThe Verify Wizard lets you check an archive file for correctness and consistency, andto check if all the elements required for deploying your application are in place. Afterverifying archives individually and ensuring there are no errors, the assembly levelverification involves verifying other resources that will be built into an application.For example, the Verify Wizard will verify the existence and correctness of URIs(Uniform Resource Identifiers), but not EJB or JNDI links.To verify an archive:1 From the Wizards menu on the Console, select Verify Wizard.Figure 7.8 Verify Wizard2 Choose the verification level:• Developer: This is the lowest verification level. All xml is checked for syntax aswell as standard and proprietary keywords relevant to the current archive type.Consistency across the archive is checked, but no external resources are verifiedat this level.• Assembler: Once the archives are individually verified and are correct, otherresources built into an application will start to be verified. For example, thislevel will verify the existence and correctness of URIs, but not EJB or JNDI links.• Deployer: (the default) All checks are turned on. EJB and JNDI links arechecked at this level as well as the operational environment in which theapplication is to be deployed.3 Specify the additional options, if desired, then click OK.If errors are found, they appear in a new window.Wizards 7-9

XML Migration WizardXML Migration WizardThis utility helps you migrate JAR files containing EJBs based on version 1.2 of theJ2EE specification to EJBs based on version 1.3 of the J2EE specification. This wizardalso delivers functionality to migrate modules from J2EE 1.3 to J2EE 1.2. The wizardmigrates the XML deployment descriptors only. Any non-Borland vendor-specificinformation stored in the 1.2 deployment descriptor (that is, a *.ser file) will not bemigrated.Note The XML Migration utility does not migrate CMP 1.1 to CMP 2.0.To fully migrate modules from J2EE 1.2 to J2EE 1.3, several additional steps arerequired:1 The source code must be modified to match the EJB 2.0 specification and new classfiles generated. For example, the signature of the ejbCreate() method is differentbetween 1.0 and 1.1 versions, and needs to be modified.2 You should use the Deployment Descriptor Editor to add and/or modifydeployment information that was absent, or was not migrated from the originaldeployment descriptor, for example, EJB JNDI names, transaction attributes andother information.Note You can also migrate JAR files using iastool commands. For more information, seeChapter 10, “iastool command-line utility”.To upgrade an EJB 1.2 JAR file to a 1.3 JAR file or downgrade a 1.3 JAR to a 1.2 JAR:1 From the Wizards menu on the Console, select XML Migration Wizard2 Select the Upgrade or Downgrade option.3 Click Browse to select the modules you want to migrate4 Make your selections and click OK.5 To designate an output file from the process, either enter a file name or clickBrowse to navigate to a directory.6 Click Finish.7-10 User’ s Guide

XML Migration WizardFigure 7.9XML Migration Wizard7 The results display in a new window.Figure 7.10XML Migration Wizard ResultsWizards 7-11

Stub Generation WizardStub Generation WizardStub generation is required so that modules are in a form that the server is expecting.For EJBs, this involves generating client and server-side stubs. Because stubs aregenerated from the Console and not on the server, any classes that are needed duringstub generation (that is, compile time dependencies of the Home and Remoteinterfaces of the beans) will need to be available to the Console.The Stub Generation Wizard lets you create the following types of archives:• a single client JAR file that is suitable for use by a non-container client application(for example, a CORBA server/client). As a result, EAR modules will be ”flattenedout” so that standard Java classloaders can be used.• a single JAR file containing just the generated stub classes (both client- and serverside)required for server deployment.• a manually deployable JAR file that all the stubs classes contains generate JAR fileswith all necessary stubs for manual deployment to the Borland Enterprise Server,and generate a stubs only library file containing only generated stub classes.Creating client stubs for non-container applicationsTo create client stubs for non-container applications:1 From the Wizards menu on the Console, select Stub Generation Wizard.Figure 7.11 Stub Generation Wizard: Step 12 Choose Create a client library file, then click Next.7-12 User’ s Guide

Stub Generation WizardFigure 7.12 Stub Generation Wizard: Step 23 Click Add to select the module or modules that you want to generate the stub filesfor, then click Next.Figure 7.13Stub Generation Wizard: Step 3 (for client stubs)4 To designate an output file from the process enter a file name (or click Browse tonavigate to a directory location and then enter a file name).5 Optionally, click the Edit button to open the Class Path Editor to add archives andclasspaths in the Classpaths field:• Click Add Archive to browse for Jars.• Click Add Path to browse for paths.Wizards 7-13

Stub Generation WizardFigure 7.14Class Path EditorBy default, if you are deploying multiple modules, then all modules are placed onthe classpath of the stub generator. So, if your beans have references to beans inother Jars, then a multiple deployment requires that you add the other Jars to theclasspath.6 Optionally, enter any command line arguments for the java2iiop and javaccompilers that may be needed by the file. Click the More Info button for a detailedusage statement of Java2IIOP or refer to the Borland Enterprise ServerProgrammer's Reference for information about Java2IIOP.7 Click Finish.Creating a 'stubs only' library fileThis wizard generates a single JAR file containing just the generated stub classes.To create a stubs only JAR file containing just the generated stub classes:1 From the Wizards menu on the Console, select Stub Generation Wizard.2 Choose Create a 'stubs only' library jar file, then click Next.3 Click Add to select the module or modules that you want to generate the stub filesfor, then click Next.7-14 User’ s Guide

Stub Generation WizardFigure 7.15Stub Generation Wizard: Step 3 (for a stubs only file)4 If you do not want to generate server-side stub files, check Generate client stubsonly.5 To designate an output file from the process, either enter a file name (or clickBrowse to navigate to a directory location and then enter a file name).6 Enter any Jars or classpaths on which your beans depend in the Classpath field orclick Edit to use the ClassPath Editor.7 Optionally, enter any command line arguments for the java2iiop and javaccompilers that may be needed by the file. Click the More Info button for a detailedusage statement of Java2IIOP or refer to the Borland Enterprise ServerProgrammer's Reference for information about Java2IIOP.8 Click Finish.Creating a JAR suitable for manual deploymentYou can use the Stub Generation Wizard will generate JAR files containing all of thenecessary stubs for a manual deployment to the Borland Enterprise Server. This canbe useful if you want to create a deployable JAR and deploy it later.To create a server-side deployable JAR for manual deployment:1 From the Wizards menu on the Console, select Stub Generation Wizard.2 Choose Create a 'stubs only' library jar file, then click Next.3 Click Add to select the module or modules that you want to generate the stub filesfor, then click Next.Wizards 7-15

Remove Stubs WizardFigure 7.16Stub Generation Wizard: Step 3 (for a deployable JAR file)4 Either click Overwrite the original modules, or to keep the originals intact, enteran output file (or click Browse to navigate to a directory location and then enter afile name).5 Enter any Jars or classpaths on which your beans depend in the Classpath field orclick Edit to use the ClassPath Editor.6 Optionally, enter any command line arguments for the java2iiop and javaccompilers that may be needed by the file. Click the More Info button for a detailedusage statement of Java2IIOP or refer to the Borland Enterprise ServerProgrammer's Reference for information about Java2IIOP.7 Click Finish.Remove Stubs WizardThe Remove Stubs Wizard lets you remove any existing stubs from your JAR files.To remove existing stubs from a JAR file:1 From the Wizards menu on the Console, select Remove Stubs Wizard.2 Click Add to select the module or modules that you want to remove stub from,then click Next.3 Either click Overwrite the original modules (each modified JAR will be given thesame name as the original module within this directory, or to keep the originalsintact, enter an output file (or click Browse to navigate to a directory location andthen select a file).4 Click Finish.7-16 User’ s Guide

Apply Patch WizardApply Patch WizardJAR WizardThe Apply Patch Wizard lets you apply a patch or a set of patches to a JAR file.To apply a patch to a JAR file:1 From the Wizards menu on the Console, select Apply Patch Wizard.2 Enter the name of the JAR file to which you want to apply the patch (or clickBrowse to navigate to a directory location and then select a file).3 Click Add to select the module or modules that contain the patches you want toapply.4 Enter the name of the output file that will be created as a result of this process (orclick Browse to navigate to a directory location and then select a file).5 Click Finish.Use the JAR Wizard to compress or uncompress files in a JAR file.To compress or uncompress your JAR files:1 From the Wizards menu on the Console, select Jar Wizard.2 Select either Compress input jar or Decompress input jar.3 Enter the name of the JAR file to compress or uncompress (or click Browse tonavigate to a directory location and then select a file).4 Enter the name of the output file that will be created as a result of this process.5 Click Finish.Registration WizardNoteUse the Registration Wizard to register your Borland Enterprise Server product:1 Select the Servers view in the Console.2 Expand the Enterprise Servers node in the navigation tree and click on the serveryou want to register.3 To start the Registration Wizard, right-click the server node and choose Registerserver from the context menu, or click the Register Server button in the right paneof the Console, then follow the instructions in the Registration Wizard.If you are a Borland Community member, or if you have a Borland SoftwareRegistration Account from a previous electronic product registration, you can use theQuick Registration option. For more information about becoming a BorlandCommunity member, visit the Borland Developer Network site at http://community.borland.com.Wizards 7-17

Export EJB as a Web Service WizardNoteFor more information on licensing and the registration wizard refer to ”Licensingand registering the server” in Chapter 2, “Using the Borland Management Console”.Export EJB as a Web Service WizardNoteUse the Export EJB as a Web Service Wizard to export a stateless Session bean as aWeb service. Upon completion, the wizard automatically sends requests to the serverto generate and deploy the service:This demonstration uses the animal example located in the install_dir/examples/webservices/ejb directory and you must first run the ant utility to create theanimal_ejb.jar file and its beans. Then you must deploy the animal_ejb.jar on anyPartition using the Deployment Wizard or the iastool utility deploy tool. For moreinformation see “Deployment Wizard” on page 7-3 and Chapter 10, “iastoolcommand-line utility”. For more information on the ant utility and how to use theWeb services examples, see the Borland Enterprise Server Developer's Guide.1 In the Console, select the Servers View if it is not already in view.2 Navigate to a deployed module and expand the node to view the beans it contains.Figure 7.17Starting the Export EJB as a Web Service Wizard3 Right-click on a stateless Session bean, then choose Export EJB as a Web Service.7-18 User’ s Guide

Figure 7.18 Export EJB as a Web Service Wizard: Step 1Export EJB as a Web Service Wizard4 Enter a name for the Web service and a name for the War file you wish to createand deploy. For the example, the Web Service Name is Animal and the War Name isanimal_ejb. At this point, either click Finish to create your Web service with thedefault settings or click Next to supply additional information as described below.Figure 7.19 Export EJB as a Web Service Wizard: Step 25 Select the Remote Interface Methods listed that you want to make available in theWeb service. For the example, the sleep and talk methods are selected. At thispoint, either click Finish to create your Web service with the remaining defaultsettings or click Next to supply additional information as described below.Wizards 7-19

Export EJB as a Web Service WizardFigure 7.20 Export EJB as a Web Service Wizard: Step 36 Edit the XML deployment descriptor file as needed, then either click Finish tocreate your Web service with the default settings or click Next to supplyadditional information as described below.Figure 7.21 Export EJB as a Web Service Wizard: Step 47 Enter any Jars or classpaths on which your beans depend in the Classpath field orclick Edit to use the ClassPath Editor.8 Optionally, enter any command line arguments for the java2iiop and javaccompilers that may be needed by the file. Click the More Info button for a detailedusage statement of Java2IIOP or refer to the Borland Enterprise ServerProgrammer's Reference for information about Java2IIOP.7-20 User’ s Guide

Export EJB as a Web Service Wizard9 When you are done, click Finish.10 When the process has completed, click Close.11 To verify that the deployment was successful, click on the newly created WAR filenode in the navigation tree, then select a URL located in the Additional WebModule Properties box near the bottom of the work pane on the right side of theConsole, then click Test URL. (You may need to use the scroll bar on the right sideof the work pane to view the Additional Web Module Properties box.)12 To examine the WSDL (Web Service Description Language) file, complete thelocation or address field in your Web browser with the full URL address of theWSDL file that corresponds to the EJB's Web service. For example, enter services/Animal?wsdl to supply an address such as:http://myserver:8080/animal_ejb/services/Animal?wsdlWizards 7-21

7-22 User’ s Guide

Chapter8Chapter8Using theApplication Assembly ToolBorland Enterprise Server includes an Application Assembly Tool that lets youperform a variety of tasks on archives that will be deployed on one or more servers,such as:• Adding files to an archive• Viewing archive files• Editing archive files• Removing archived files• Creating archive files• Verifying archive filesThe tool can open a variety of archive files including:• Enterprise Application Archives (EARs)• WEB Application Archives (WARs)• Resource Adapter Archives (RARs)• EJB JARs• Client Jars• Zip files• DAR (a Borland proprietary product that stores JNDI definitions)The Application Assembly Tool lets you create a variety of archive files including:• Enterprise Application Archives (EARs)• EJB Jars• WEB Application Archives (Wars)• Client JarsUsing the Application Assembly Tool 8-1

Starting the Application Assembly toolImportant• Connector modules• Library files• J2EE version 1.2 archives (EARs, EJB, Web, and client-side Jars)The tool also lets you extract files from an archive and verify archive files at theassembly level.The Application Assembly tool has a number of practical uses. It not only enablesyou to view and edit existing files in the archive; but lets you quickly assemblearchives. For example, if you have forgotten to add an image file to a JAR file, youcan use the Application Assembly tool to add the image file to the JAR withouthaving to rebuild the JAR.For documentation updates, go to www.borland.com/techpubs/bes.Starting the Application Assembly toolThe Application Assembly tool can only be started from the Console:1 Start the Console.2 From the Tools menu, select Assembly Tool, or click the Assembly Tool icon inthe toolbar.Figure 8.1The Application Assembly ToolWith the Application Assembly tool open, you can begin to add files to an (as yetunnamed) archive. Each archive, when created, contains a manifest file which isautomatically generated by the Application Assembly tool.8-2 User’ s Guide

Opening an archiveOpening an archiveTo open an archive:1 Open the Application Assembly tool.2 Select the Open option from the File menu.3 Navigate to the archive file that you want to use and select it, then click OK.The archive opens and its contents are displayed.Figure 8.2 An open archive filePerforming actions on an archiveOnce the archive is created, you can perform a variety of actions on it and the filesthat it contains.Adding files to an archiveFiles can be added to a new or existing archive. To add files to an archive:1 Open the Application Assembly tool.2 Open an archive, then select Add from the Module menu.3 Select the files to add to the archive.• To add one or more files, click the Add Files button.• To add the contents of an entire directory, click the Add Directory button.4 Navigate to the file or directory that you want to add and select it, then click OK.Using the Application Assembly Tool 8-3

Performing actions on an archive5 Choose either the Relative path (the default) or Absolute path radio button. Whenconstructing J2EE archives, you should use relative paths only.6 Leave the Compress entries box checked (the default) unless you do not want tocompact the files you are adding to the archive.7 If adding a directory, leave the Include subdirectories box checked (the default) ifyou also want to recursively add the directories and files contained in thedirectory you are adding.8 When you have finished adding entries, click OK.Figure 8.3Adding files to an archiveEditing text files in archivesOnce a text file has been added to an archive, it can be edited without the need toextract it from the archive. To edit a text file:1 Open an archive.2 Double-click on an editable file in the archive to open it in a text editor window.3 Edit the file as needed, then click Save.8-4 User’ s Guide

Saving an archiveFigure 8.4Editing a file in an archiveRemoving files from an archiveTo remove files from an archive1 Select the files to be removed.2 From the Module menu, select the Remove Files.Saving an archiveTo save an archive file, select Save from the File menu.To save an archive that you have created with a different name:1 Select the Save As option from the File menu.2 Specify the name and the location of the file to be saved.3 Click Save.Editing archive filesTo edit any type of file in an archive:1 Open the archive.2 Right-click on the file and select Text Editor from the menu.3 Enter the required changes.4 Click Save.Using the Application Assembly Tool 8-5

Creating archivesCreating archivesTo create a new archive file:1 Select New from the File menu.2 On the New Module Wizard, select the type of archive you want to create and theJ2EE version that you want to use, then click Next.Figure 8.5New Module WizardThe New Module Wizard asks you to supply additional details that apply to thetype of archive you have selected. The details you are asked to supply varydepending on the archive type.3 When you are done supplying the details, click Finish.The New Module Wizard creates the fundamental foundation files required forthe archive type selected and opens it as an untitled archive. If you make unsavedchanges to an archive file, the Application Assembly Tool prompts you to save itbefore it opens the new archive.8-6 User’ s Guide

Extracting modulesFigure 8.6Creating an archive fileExtracting modulesThe Application Assembly tools lets you uncompress one or more files in an archive.To extract modules in an archive:1 Open an archive.2 You can either:• Leave all the modules unselected if you want to extract them all.• Click on one or more modules if you want to extract only selected modules.3 Select Extract from the Module menu.Figure 8.7 Extract Modules window4 In the Output directory field, enter the location where you want to store theextracted files or use the Browse button to find a location.Using the Application Assembly Tool 8-7

Verifying archivesVerifying archivesThe Application Assembly tools lets you check an archive file for correctness andconsistency, and to check if all the elements required for deploying your applicationare in place. After verifying archives individually and ensuring there are no errors,the assembly level verification involves verifying other resources that will be builtinto an application. For example, the Application Assembly tool will verify theexistence and correctness of URIs (Uniform Resource Identifiers), but not EJB or JNDIlinks.To verify a an archive:1 Open the archive.2 Select Verify from the Module menu3 On the Verify Module window, choose the verification level:• Developer: This is the lowest verification level. All xml is checked for syntax aswell as standard and proprietary keywords relevant to the current archive type.Consistency across the archive is checked, but no external resources are verifiedat this level.• Assembler: Once the archives are individually verified and are correct, otherresources built into an application will start to be verified. For example, thislevel will verify the existence and correctness of URIs, but not EJB or JNDI links.• Deployer: (the default) All checks are turned on. EJB and JNDI links arechecked at this level as well as the operational environment in which theapplication is to be deployed.Figure 8.8Verify Module window4 Specify the additional options, if desired, then click OK.If errors are found, they appear in a new window.Supported archive typesSupported archive types are: EAR, WAR, JNDI, RAR, Client Jars, DAR, and ZIP.The typical archive verification process includes the following checks:• A pass over the XML code, checking for correct XML syntax.8-8 User’ s Guide

Verifying archives• Verification of the semantics of the standard and proprietary XML descriptors,and the compliance with the required descriptors for each supported archive type.Verification always occurs in a hierarchical fashion, starting with the top module. Ifverification is correct, verification continues recursively working throughsubmodules and finally checking for inter-archive links.Using the Application Assembly Tool 8-9

8-10 User’ s Guide

Chapter9Chapter9Using theDeployment DescriptorEditorThe Borland Management Console includes a Deployment Descriptor Editor(DDEditor) that can be used to change and add deployment information in a J2EEarchive's deployment descriptor file. The DDEditor is available in all three editions ofthe Borland Enterprise Server. The Borland Enterprise Server is J2EE 1.3 compliantbut also back-compatible with J2EE 1.2 descriptors. The objects that can be edited are:Descriptors (producing standard and proprietary Borland XML)• EARs (producing application.xml)• WARs (producing web.xml)• EJB 1.1 JARs (producing ejb-jar.xml)• EJB 2.0 JARs (producing ejb-jar.xml)• Application Client JARs (producing application-client.xml)• JNDI Definitions (Borland proprietary product)Archives• J2EE 1.3 Application EARs• J2EE 1.2 Application EARs• Servlets 2.2 WARs• Servlets 2.3 WARs• JNDI Definitions - DARs (Borland proprietary product)• Resource Adapter Archives (1.0)• Application Client JARs (1.2 and 1.3)Using the Deployment Descriptor Editor 9-1

Archive directory structuresImportant• EJB JARs (1.1 and 2.0)This chapter gives an overview of component information included in the descriptorfile, explains how to use the DDEditor included with the Borland Enterprise Server,and provides a list of descriptor information you can edit in the file.For documentation updates, go to www.borland.com/techpubs/bes.Archive directory structuresApplications are developed within a specified directory structure so that they can bearchived and deployed on a J2EE server. All classes, files, servlets and otherresources are organized hierarchically in a directory.About the descriptorJ2EE applications are composed of one or more J2EE components and one J2EEapplication deployment descriptor. The deployment descriptor describes theapplication's components as modules.A component deployment descriptor is an XML file that describes the units within anarchive (module) being deployed. The information provided in the deploymentdescriptor is necessary for deploying to the Borland Enterprise Server. Deploymentdescriptors tell the Deployer how to deploy an application. The J2EE specificationdefines some of the deployment descriptors like the ejb-jar.xml and web-app.xmldescriptors. Borland provides additional deployment descriptors with the requiredinformation to deploy components in the Borland Enterprise Server.You can edit deployment descriptors by using the Borland Enterprise Server'sDDEditor tool. Code generation tools such as JBuilder can also automaticallygenerate deployment descriptors, or you may code them yourself.For more information about the structure and content of the deployment descriptorfile, see the Borland Enterprise Server Developer's Guide.Usage conditionsThe DDEditor can be used with a wide range of archive and descriptor types. Thereare a number of usage considerations for each of these.General1 The DDEditor automatically creates a deployment descriptor that is XML-based soyou do not have to learn XML.2 You can edit an archive file that contains embedded XML or you can edit the XMLfile directly.9-2 User’ s Guide

Usage conditions3 Basic code editing features are included in the DDEditor when editing XMLdirectly:• CTRL+F = find and replace• CTRL+G = go to line number4 The DDEditor conforms to the semantic rules specified in Sun's DTD. Itimplements these rules on the data you enter.5 The DDEditor automatically sets up the Borland-specific extensions in a separatefile.6 Navigation pane, in this document refers to the left pane of the DDEditor, andwork pane refers to the right pane of the DDEditor.EARsThe EAR is the basic deployment unit. The EAR is not however, very useful withoutarchives with which to populate it. Therefore, the basic procedure of creating an EARinvolves:1 Creating a new EAR.2 Populating the EAR with its component parts such as WARs, Application Clientsand EJB JARs, or create them within the EAR.WARsWARs are archives that are intended for use with Web applications. They supportobjects such as servlets JSPs, HTML and so on.If the distributable flag is set on servlets, it indicates to the web container (Tomcat)that this web application's servlets and JSPs are capable of running in a separateVirtual Machine and/or failing over to another container or Partition. Accordingly,there are a number of restrictions/implementation requirements that any servletmarked as distributable must observe:• You cannot use the servlet context to share information between servlets. Youhave to use a Session instead.• Any object that you want to share in the Session must implement serializable. Ifyou try to stuff something non-serializable into the session, you'll get a InvalidArgument exception.WAR directory structuresThe root of this hierarchy defines the document root of your Web application. Allfiles under this root directory can be served to the client except for files under the WEB-INF directory (under the root directory). The name of your Web application is used toresolve requests for components of the Web application.Using the Deployment Descriptor Editor 9-3

Usage conditionsPlace all private files in the WEB-INF directory. All files under WEB-INF are private andare not be served to the client.WebApplicationName/: Static files such as HTML and JSP files should go in thisdirectory. This directory is the document root of the Web Application./WEB-INF/web.xml: This is the Web application deployment descriptor that configuresthe Web application./WEB-INF/borland.xml: This is the Borland-specific deployment descriptor that defineshow named resources in the web.xml file are mapped to resources that are locatedsomewhere else in the server. This descriptor file is also used to define JSP and HTTPsession attributes./WEB-INF/classes: This contains server-side classes such as servlets and utility classes./WEB-INF/lib: This contains the JAR files used by the Web application. This includesJSP tag libraries./WEB-INF/classes: This contains server-side classes such as servlets and utility classes./WEB-INF/lib: This contains the JAR files used by the Web application. This includesJSP tag libraries.EJBsSome things to remember about using the editor with EJBs include:• You can edit an EJB JAR file that contains embedded XML, or you can edit theXML file directly.• If you launch the DDEditor as a stand-alone application and the BorlandEnterprise Server is running, you should not edit a JAR file deployed in a BorlandPartition.• The Set Classpath button works with EJB JAR files only.• Entity Beans can use either JDBC 1 or JDBC 2 datasources. JDBC 1 datasources arelocal to an EJB JAR. JDBC 2 datasources can be used by any EJB.For information about working with JDBC2 datasources, see the Borland EnterpriseServer Developer's Guide.JNDI DefinitionsRemember when using the DDEditor with JNDI definitions that they can bedeployed independently of an application or as part of an application archive (EAR).9-4 User’ s Guide

Starting the editorStarting the editorYou can run the DDEditor as a stand-alone application or as part of the ManagementConsole.You can also start the editor by selecting a file from the Deployed Modules node inthe navigation tree of the Console. Right-click on the module you want to edit andselect ”Edit deployment descriptor” from the context menu. A process window willappear and then launch the DDEditor.To start the DDEditor:1 Depending on the choices you made during installation, use one of the followingmethods to start the editor:• On Windows NT, click the Start button and choose Deployment DescriptorEditor from the Borland Enterprise Server program group.• Start the Console and choose DDEditor from the Tools menu.• If you have added the Borland Enterprise Server's bin directory to your path,open a command window and enter the following commandddeditor where filename is the name of the XML or archive file you wish to edit.(Otherwise change to the bin directory and enter the same command.)2 If necessary, select the deployment descriptor you want to edit:3 Choose Open from the File menu to open an existing deployment descriptor.4 Choose New from the File menu to create a new deployment descriptor or archive.5 When the main Descriptor Editor window appears, use the tabs to examine or adddescriptor information. You can use the Navigation panel (left side of BorlandManagement Console) to examine, create or rename your files.The following sections describe the types of information you can edit in thedeployment descriptor.Adding descriptorsThe Borland DDEditor enables you to create deployment descriptors for each type ofarchive, as well as for JNDI definitions.The deployment descriptor is an XML file which follows the Document TypeDefinition (DTD) approved by Sun Microsystems. Deployment descriptors contain aset of properties that describe how the container deploys an archive.Using the Deployment Descriptor Editor 9-5

Adding descriptorsThe types of information in the descriptorThe information in the deployment descriptor can be divided into two basic kinds ofinformation:• Structural information. Structural information describes the structure of archivefiles (and JNDI definitions) and their modules. For archive files, this involvesgeneral information like ”Display Name”, ”EJB JAR name”, ”EJB Client JARname”, and ”Authorization domain”. In the case of enterprise beans, the structuralinformation declares the enterprise bean's external dependencies. Thisinformation is required and cannot, in general, be changed (doing so could breakthe enterprise bean's function).• Application assembly information. Application assembly information describeshow the archive files and enterprise beans are composed into a larger applicationdeployment unit and how they interact with the application as a whole. Assemblylevel information can be changed without breaking modules' function.The following section describes the ”Structural” and ”Assembly” information for thevarious deployable modules.Enterprise bean structural informationAll enterprise beans:• enterprise bean class• enterprise bean home interface• enterprise remote interface• enterprise bean local home interface• enterprise bean local interface• enterprise bean home JNDI name• enterprise bean local home JNDI name• environment entries• EJB references (if an enterprise bean references another enterprise bean)• resource (factory) references (if a datasource is used)• security role references• security identityEnterprise session beans:• Session bean's state management type• Session bean's transaction type9-6 User’ s Guide

Adding descriptorsEnterprise entity beans:• Entity bean's persistence type• Entity bean's primary key class• Entity bean's reentrant behaviorEnterprise entity beans with container-managed persistence:• Container-managed fields• Container-managed relationshipsEnterprise bean application assembly informationYou can specify any of the following application assembly information in yourdeployment descriptor.• Binding of enterprise bean references• Security roles• Method permissions• Security role reference links• Exclude lists• Container transactions for Entity beansCreating Deployment DescriptorsDeployment descriptors contain the same information that is used in the creation ofan archive, so no detailed explanation will be included here.To create new definition descriptors:1 Open the DDEditor.2 Select New from the file menu.3 The Object Gallery window appears. Select a descriptor or archive type from oneof the four tabs in the Object Gallery.Using the Deployment Descriptor Editor 9-7

Adding descriptorsFigure 9.1The Object Gallery4 Assign properties to the descriptor.5 Once the descriptor is as you wish, select Save from the File menu.6 Select a folder and click Save. The descriptor is saved as the Descriptor_Type.xml.In all cases, excepting JNDI descriptors there is also a proprietary XML file.Creating a JNDI definition descriptorNoteThe process of creating a JNDI definition descriptor is similar to creating anydescriptor type.To create a JNDI definition descriptor:1 Open the DDEditor.2 Select New from the file menu.3 Select the JNDI Definitions tab in the Object Gallery.4 Select JNDI Definitions and click OK.5 To add one of the following datasources:• New JDBC Datasource• New Sonic JMS object• New JNDI objectright-click the jndi-definitions object in the Navigation pane and select one of theoptions. When the JNDI name window appears, enter a name (after the prependedname given).6 Once the descriptor is as you wish, select Save from the File menu. The descriptoris saved as the jndi-definitions.xml.New JDBC Datasources, Sonic JMS objects and JNDI objects added will appear inthe ”Standard XML” tab.9-8 User’ s Guide

Adding descriptorsJNDI definitions and datasource archives (DARs)NoteBorland provides mechanisms for deploying both JDBC resource factories and JMSconnection factories.The Borland Enterprise Server's EJB Container creates datasources for you. The onlything you need to do for the Container is specify the information about the resourcesto which your application(s) need to connect and bind the datasource to JNDI. Oncebound, you can reference the datasource from your enterprise beans using the element in your deployment descriptor.Datasources are bound to JNDI when they are deployed as a part of a JNDIdefinitions module. The module is similar to other J2EE standard Java archive typesand ends in the extension .dar. The module is also referred to as a DAR. The DARadds to the standard J2EE module types and can be packaged as part of an EAR ordeployed as a standalone. Since datasources are contained in their own module, theyappear in the Server tree of the Borland Enterprise Server's Console making it easy toenable, disable and edit (by launching the DDEditor) by right-clicking theirrepresentations in the tree.A DAR is not part of the J2EE specification. It is a Borland-specific implementationdesigned to simplify the deployment and management of connection factories. Donot package connection factory classes in this archive type. Connection factoryclasses must be deployed as a library to individual partitions.Since the Container constructs the connection factory class, the only thing you mustprovide the DAR is an XML descriptor file called jndi-definitions.xml. Like otherdescriptors, this is in the META-INF directory of the DAR. A DAR looks like this:META-INF/jndi-definitions.xmlYou deploy the DAR containing the descriptor file just as you would any other J2EEmodule using either the Console or command-line utilities, or as part of an EAR.Creating a JNDI definitions archive (DAR)To create a JNDI definitions archive (DAR):1 Open the DDEditor.2 Select New from the file menu.3 Select the JNDI Definitions tab in the Object Gallery.4 Select JNDI Definitions Archive and click OK.5 To add one of the following datasources:• New JDBC Datasource• New Sonic JMS object• New JNDI objectUsing the Deployment Descriptor Editor 9-9

Adding descriptors6 Right-click the jndi-definitions object in the Navigation pane and select one of theoptions. When the JNDI name window appears, enter a name (after the prependedname given).7 Once the archive is as you wish, select Save from the File menu.8 Assign a name to the archive and it is saved as a .dar file.Setting properties for datasourcesOnce you've created a datasource you can view and configure its properties. To viewor configure datasource properties:1 Select the datasource, for example, ”database” (for a JDBC datasource) in thenavigation pane.2 For JDBC datasources you can set main properties, pool properties and driverproperties.• Main: This tab allows you to select a pre-configured, commonly usedDatasource Type (JDataStore, Oracle, Oracle.XA, Sybase, JDBC2, etc.) or addone not listed. In addition, if you select a pre-configured Datasource Type, otherproperties required for that source are provided such as Class name, Max poolsize, etc. There are several fields you configure, such as Driver type, Databasename, Server name, port number, user, password, etc. These properties are partof the XML also, which can be viewed and edited in the XML tab. See XMLexample below:serial://datasources/myDriveroracle.jdbc.xa.client.OracleXADataSourceFalsedriverTypeEnumeratedthinportNumberInteger15213 Pool Properties: This tab allows you to set the pool properties of Name, Type andValue. Depending on the Type, Value options change. The Names include:• initSQL• description• reuseStatements• busyTimeout9-10 User’ s Guide

Adding descriptorsNote• idleTimeout• queryTimeout• maxPoolSize• dialect• isolationLevel• resSharingScope• refreshFrequency• connectionType• waitTimeout• dbPingSQL4 Driver Properties: This tab allows you to configure and add driver properties.5 For JMS objects you can set main and additional properties.• Main: This tab allows you to select a pre-configured, commonly usedConnection Factory such as QueueConnectionFactory,TopicConnectionFactory, XAQueueConnectionFactory,XATopicConnectionFactory, etc. In addition, there are several fields youconfigure, such as User, Password, Connect ID, Client ID and Sequential andLoad Balancing values.• Properties: Any parameters that are required for SonicMQ are pre-configuredhere. Otherwise, you can configure a Name (brokerURL, sequential,loadBalancing), a Type and a Value. These properties are part of the XML element, which can be viewed and edited in the XML tab. SeeXML example below:serial://jms/messageprogress.message.jclient.QueueConnectionFactorybrokerURLStringlocalhost:2506sequentialBooleanfalseloadBalancingBooleantrueOne JNDI Definition module is pre-deployed in the Borland Enterprise ServerPartition and is easily configurable using the server's tools. This module is calledUsing the Deployment Descriptor Editor 9-11

Adding EAR archivesNotedefault-resources.dar and jms-resources.dar. Each of these contains some preconfigured connection factories that you can edit by right-clicking the module in theserver tree and selecting the DDEditor from the context menu.For more information on defining JDBC datasources and connection factories refer toDatasources in Borland Enterprise Server in theBorland Enterprise Server Developer'sGuide.Adding EAR archivesWhen creating J2EE compliant applications, the EAR forms the basis of deployment.When creating an EAR for deployment with Borland Enterprise Server, therecommended procedure is:1 Open the DDEditor.2 Select New from the file menu.3 Once the Object Gallery appears, select either 1.3 Application Archive from theJ2EE 1.3 Tab or 1.2 Application Archive from the J2EE 1.2 Tab.4 Assign properties to the EAR archive.5 Once the EAR archive is as you wish, select Save As from the File menu.6 Assign a name to the archive with the extension .ear and click Save.EAR propertiesSeveral EAR archive properties are displayed on the Properties pane and can beedited after creation.General TabUse the General Tab to enter or change general information about the EAR archive.The information includes:Application Display Name: The logical name assigned to the application that isdisplayed by the Console.Application File Name: The name and location of the EAR file that is defined by thearchive.Description: A summary of the application's purpose and function. This informationis optional.Authorization domain: An authorization domain defines the set of rules thatdetermines whether a user belongs to a role or not. When an access decision isperformed (see “Assigning method permissions” on page 9-37 and “Adding securityroles and method permissions” on page 9-35), the authorization domain maps thelogical roles required to access a resource to a set of rules. It consults a database ofrules that determine whether a user belongs to a given role. Rules describe whatattributes and corresponding values are required for a user to belong to a role. The9-12 User’ s Guide

Adding WAR informationcaller's security attributes are then matched with the required rules to determinewhether the caller's security attributes satisfy the rules required for access.The authorization domain an application uses is determined by the deployment descriptor, or the domain() method. The authorization-domain tag isused to bind a JAR, WAR, or EAR to an authorization domain. This tag does notdefine an authorization domain but merely binds the resources in the J2EEapplication to the specified authorization domain.The authorization-domain element is a Borland-specific element and appears in theVendor XML tab.Context Roots TabThis tab allows you to specify the proper URI configuration for your servlets,ensuring they are only called from the proper URI mapping.Web URI: The URI pattern of the servlet, for example, ”helloweb.war”.Context Root: Name of the Web application from which the servlet is called.Properties TabThis tab allows you to set various environment properties relative to your WAR:Name: The name of the environment variable.Type: The environment variable type.Value: The value of the environment variable.XML TabYou may, if you choose, edit the XML directly. Choose either the Standard or VendorXML Tabs to edit. Once you are finished, click Apply Changes and save the archive.Adding WAR informationTo create a WAR archive:1 Open the DDEditor.2 Select New from the file menu.3 Once the Object Gallery opens, select either Servlets 2.2 WAR from the J2EE 1.2Archive Tab or Servlets 2.3 WAR from the J2EE 1.3 Archive Tab.4 Assign properties to the WAR archive.5 Once the WAR archive is as you wish, select Save from the File menu.6 Assign a name to the archive with the extension .war and click Save.Using the Deployment Descriptor Editor 9-13

Adding WAR informationWAR propertiesWAR archive properties are displayed on the Properties pane and can be edited aftercreation.GeneralWAR Display Name: The logical name assigned to the Web component that isdisplayed by the Console, for example, ”HelloWebTier”.WAR File Name: The name and location of the WAR file that is defined by thearchive, such as, ”helloweb.war”.Description: A summary of the Web component's purpose and function. Thisinformation is optional.Context Root: Name of the web application calling the servlets, for example, ”hello”.Authorization domain: See previous section on Authorization domains.Distributable: This check box indicates whether the component is programmedappropriately to be displayed in a distributed service container.Session Timeout: Determines how long before an inactive session is terminated.Context ParamsContext Parameter: Servlet context initialization parameters.Value: The value of the servlet context initialization parameters.Environment Description: A brief description of the purpose of the environmentvariable.Property: The name of the environment variable.Value: The value of the environment variable.Type: The environment variable type. The options are:• Boolean• String• Integer• Character• Double• Byte• Short• Long• Float9-14 User’ s Guide

Adding WAR informationFigure 9.2Adding an environment propertyEJB ReferencesAn EJB reference is a pseudonym for the JNDI location that you want to lookup abean. The pseudonym may not actually correspond to the actual JNDI location that isin your bean. Your code looks up a home via its pseudonym, and then you bind thepseudonym to the JNDI location, perhaps using symbolic links (links are describedbelow).To use a programmatic example, if Bean A needs to use Bean B, you can simplydeclare all the necessary information about Bean B in an EJB reference. The deployerthen knows that Bean A uses one other bean, Bean B. This is useful because thedeployer now knows which class files Bean A depends on and which JNDI locationneeds to be bound. The Container's tools can easily inspect the deploymentdescriptor and verify that the deployer has done this correctly....BeanAexamples.AHome

Adding WAR informationexamples.AHomeexamples.ABeanADescription: A brief description of the function of the EJB.Name: The JNDI name used in the code.IsLink: Check to specify that this is a reference to local beans, otherwise beans arereferenced by JNDI names.Link: Links the EJB Reference to the target enterprise bean. The Link value is thename of the target enterprise bean. This information is required if IsLink is checked,otherwise it is not used.Type: Specify the EJB type. The options are:• Entity Bean• Session BeanHome: The fully-qualified name of the of the bean's home interface.Remote: The fully-qualified name of the of the bean's remote interface.JNDI Name: The JNDI name of the bean's home interface. This is not used if ISLink isspecified.EJB Local ReferencesThe EJB Local References panel lists all the enterprise bean references to the homes ofother enterprise beans within a single archive.Each EJB Local Reference describes the interface requirements that the referencingenterprise bean has for the referenced enterprise bean. The reference contains:• Description: A brief description of the bean that is referenced. This information isoptional.• Name: The name of the referenced bean. The tool tip information shows what youuse to access the Name in code.• IsLink: If checked, there is a link to a local enterprise bean and the following fieldsare filled in and read-only: Type, Home, and Remote. If unchecked, reference is toan enterprise bean outside the JAR file and you must fill in Type, Home, andRemote.• Link: Links the EJB Reference to the target enterprise bean. The Link value is thename of the target enterprise bean.• Type: The expected type of the referenced bean.• Local Home: The expected Java type of the referenced bean's home interface.• Local: The expected Java type of the referenced bean's local interface.• JNDI Name: The JNDI name of the referenced bean.9-16 User’ s Guide

Adding WAR informationError PagesType: Error type. The options are ”HTTP Error Code” or ”Java Exception Type”.Error/Exception: The name of the Error/Exception file.Location: The location of the Error/Exception file. This is relative to the root of theweb application and must start with a ”/”.These are represented in the standard XML element with and as subordinate elements.LoginThis tab is used to select an authentication method for credential verification. Whenyou have a Web browser client connecting to a servlet/JSP layer, the Web browseruser usually supplies credentials to the servlet/JSP layer and the servlet/JSP layerthen may use JAAS to authenticate the browser user. The web browser can supplythe credentials to verify the login to the web component by using any one of themethods below.• None• Digest. The web client supplies a special message digest to the web server. Thismessage digest is a symbolic transformation of the user's password and the HTTPmessage. The password itself is not sent to the server. The web server thenreproduces the message digest by performing the same symbolic transformation,but the server this time uses a secure copy of the user's password kept inpermanent storage. If the message digests match, the user is authenticated.• Client-Cert. The client can establish an identity with X.509 certificates. Optionally,the client can also ensure that a third party is not impersonating the server byreceiving X.509 certificates that authenticate the server.• Basic. The web client supplies a user name and password to the web server. Theserver checks the credentials against a permanent storage of user names andpasswords. Note that you must also specify the realm to which to authenticatehere.• Form. This is just like basic authentication except the application uses acustomizable form such as a special login screen. Note that you must also specifyURLs for the login page and error page here.Using the Deployment Descriptor Editor 9-17

Adding WAR informationFigure 9.3Setting login and error pages for Form-based authenticationMIMEThis refers to the standard XML element . The mime-mapping elementdefines a mapping between an extension and a mime type. Two correspondingattributes are and .Extension: The file extension that denotes a MIME type.Mime Type: The defined MIME type which is recognized by the Web component, forexample, ”text/plain”.Resource ReferencesThe Resource References panel lists all the enterprise bean's resource factoryreferences. This enables the application assembler and/or bean deployer to locate allreferences used by the enterprise bean.Information in the panel includes:• Description: A description of the resource reference. This information is optional.• Name: The name of the environment entry used in the enterprise bean's code.• Type: The Java type of the resource factory expected by the enterprise bean's code.This is the Java type of the resource factory, not the Java type of the resource. Thetypes available are:• javax.sql.DataSource• java.net.URL• javax.mail.Session• javax.jms.QueueConnectionFactory• javax.jms.TopicConnectionFactory9-18 User’ s Guide

Adding WAR informationThe Deployment Settings (parameters) you can specify depend upon the Javatype selected.• Authentication: An Application authentication indicates that the enterprise beanperforms the resource sign-on programmatically. A Container authenticationindicates that the Container signs on to the resource (on behalf of the webapplication) based on the principal mapping information supplied by thedeployer.• Sharing Scope: The element specifies whether connectionsobtained through the given resource manager connection factory reference can beshared. The values of this element must be either or . Thedefault is Shareable.Servlet MappingServlet: The name of the servlet.URL Pattern: Map URL to the servlet name.Tag LibrariesThe element is used to describe a JSP tag library.Library URI: The URI of the path (relative to the location of the web.xml document)to be added on onLoad.Description File Location: The is the location path of the TagLibrary description file for the tag library.Welcome FilesThe element contains an ordered list of welcome files elements.The element contains a file name to use as a default welcome file, suchas index.html.Specify the URL of the page that is first displayed when users access the webcomponent.XMLYou may, if you choose, edit the XML directly. Choose either the Standard or VendorXML Tabs to edit. Once you are finished, click Apply Changes and save the archive.Filter MappingsFilter: The logical name of the filter used to map the filter. Each filter name in a webapplication is unique.Mapping Type: The type the filter is mapped to; a servlet or URL pattern.Mapping: The container uses the filter-mapping declarations to decide which filtersto apply to a request, and in what order. The container matches the request URI to aservlet in the normal way. To determine which filters to apply, it matches filtermappingdeclarations either on a servlet-name, or on url-pattern for each filtermappingelement, depending on which style is used. The order in which the filterUsing the Deployment Descriptor Editor 9-19

Adding WAR informationmappings are invoked is the same order they appear in the list of filter-mappingelements. You may wish to view the generated XML after filling in these fields tomake sure your filter mappings are in the proper order. The mapping will be thevalue of the mapping type in the descriptor.ListenersListener Classes: Declares a class or classes in the application that must be registeredas a web application listener bean. This value must be the fully-qualified class nameof the listener class.Resource Env RefsThe element contains a declaration of a web application's referenceto an administered object associated with a resource in the application'senvironment.Resource Environment Ref Name: Specifies the name of a resource environmentreference. The reference must be a fully qualified name of a Java class or interface. Itmust be unique within a web application.Type: The resource manager connection factory type expected by servlet code. It isthe fully qualified name of a Java language class or interface.JNDI Name: JNDI name of the resource manager connection factory.NoteWeb Deploy PathsThe Web Deploy Paths tab allows you to specify exactly where to deploy the webapplication (service, engine, and host). The Borland web container (based on Tomcat)has a notion of a host being part of an engine, which in itself is a part of a service.There can be multiple hosts under an engine and there can be multiple engines undera given service. A given web application can be deployed to one or more of thesehosts. The service, engine, and host you specify using this element, override thedefaults. However, this element does accept multiple entries.The default is service=HTTP, engine=HTTP, and host=* (deploy to all hosts availableunder the specified engine).The Tomcat web container does not handle the consumption of EARs as easily as itdoes WARs. In order for the IIOP connector to handle deployment of EARs,embedded WAR files need to indicate they should be deployed to the IIOPconnector.To do this use the element provided in the web-app_2_3-borland DTD(Borland-specific). This element indicates where in the Tomcat web container”hierarchy” to deploy the WAR.The XML needed for this is shown below. You can hand code it or use the DDEditor'sWeb Deploy Paths tab:IIOPIIOPlocalhose9-20 User’ s Guide

Adding WAR informationWeb ServicesFor information on creating, editing, and deployment descriptors for Web Servicesusing Borland Enterprise Server refer to Borland Enterprise Server Web ServicesPreview in the in the Borland Enterprise Server Developer's Guide.EJB JAR propertiesEJB archive properties are displayed on the Properties panes and can be edited aftercreation.GeneralEJB Jar Display Name: The logical name assigned to the EJB JAR that is displayed bythe Console.EJB JAR File Name: The name and location of the EJB JAR file (read-only).Description: A summary of the EJB's purpose and function. This information isoptional.EJB Client JAR Filename: The name and location of the client EJB JAR file.Authorization Domain: The name of the authorization domain the JAR belongs to.The authorization domain typically maps the logical roles required to access aresource to a set of pre-defined roles.Small Icon: The file name of the 16X16 pixel icon used to identify this EJB.Large Icon: The file name of the 32X32 pixel icon used to identify this EJB.XML TabYou may, if you choose, edit the XML directly. Choose either the Standard or VendorXML Tabs to edit. Once you are finished, click Apply Changes and save the archive.Properties (environment)Information in the Properties/Environment panel(s) is used in setting environmentattributes/properties. Properties define how the object operates within a particularenvironment. Setting the properties in this panel allows you to customize the object'sbusiness logic when the it is assembled or deployed without accessing or changingthe it's source code.Property: The name of the environment variable.Value: The value of the environment variable.Type: The environment variable type. The options are:• Boolean• String• IntegerUsing the Deployment Descriptor Editor 9-21

Adding WAR informationEJB DesignerFor information about the EJB Designer, refer to the “The EJB Designer” onpage 9-42.Application Client JAR propertiesApplication Client JAR archive properties are displayed on the Properties panes andcan be edited after creation.GeneralApplication Client Display Name: The logical name assigned to the ApplicationClient that is displayed by the Console.Application Client File Name: The name and location of the Application Client file.Description: A summary of the Application Client purpose and function. Thisinformation is optional.Small Icon: The file name of the 16X16 pixel icon used to identify this ApplicationClient.Large Icon: The file name of the 32X32 pixel icon used to identify this ApplicationClient.EnvironmentSee ”Environment” description above.EJB ReferencesDescription: A brief description of the function of the EJB.Name: The JNDI name used in the code.IsLink: Check to specify that there are references to local beans, otherwise beans arereferenced by JNDI names.Type: Specify the EJB type. The options are:• Entity Bean• Session BeanHome: The fully-qualified name of the of the bean's home interface.Remote: The fully-qualified name of the of the bean's remote interface.JNDI Name: The JNDI name of the bean's home interface. This is not used if ISLink isspecified.Resource ReferencesThe Resource References panel lists all the enterprise bean's resource factoryreferences. This enables the application assembler and/or bean deployer to locate allreferences used by the enterprise bean.See information on the resource reference panel above.9-22 User’ s Guide

Adding or changing bean information• Authentication: An Application authentication indicates that the enterprise beanperforms the resource sign-on programmatically. A Container authenticationindicates that the Container signs on to the resource based on the principalmapping information supplied by the deployer.Some things to remember about EJB References include:• The target enterprise bean must be type compatible with the declared EJBreference.• All declared EJB references must be bound to the homes of enterprise beans thatexist in the operating environment.• If a Link value is specified, the enterprise bean reference must be bound to thehome of the target enterprise bean.EJB Local ReferencesSee “EJB References panel” on page 9-27.XML TabYou may, if you choose, edit the XML directly. Choose either the Standard or VendorXML Tabs to edit. Once you are finished, click Apply Changes and save the archive.Adding or changing bean informationNoteNoteNoteYou can add a new bean to the deployment descriptor or change an existing bean.You can use the Add Beans buttons on the Toolbar or use the right-click contextmenu commands to add beans.To add an enterprise bean:1 Start the DDEditor.2 Select the type of bean you wish to add:3 To add a bean, right-click the JAR in the Navigation pane and select a New Beantype from the context menu.Adding Message-Driven Beans is for EJB 2.0 only.A name dialog appears.4 Enter the name of the enterprise bean and click OK.The new bean appears in the Navigation pane.The bean name is a logical name assigned to the enterprise bean by the beanprovider. Each enterprise bean has a logical name. There is no structuralrelationship between the bean's logical name and the JNDI name assigned to thebean. The bean deployer may change the bean's logical name.5 Select the bean.A template for the enterprise bean appears in the Work pane. Use the tabs at thebottom of the pane to enter bean information.Using the Deployment Descriptor Editor 9-23

Adding or changing bean informationSetting classpath informationTo set a classpath using the DDEditor:1 Start the DDEditor and open an EJB JAR descriptor file or archive.2 Choose Set ClassPath from the Verify menu or use the Set ClassPath button.The Classpath Editor appears.Figure 9.4 The Classpath Editor3 Using the buttons provided, you can add a classpath or one or more JAR files, adda path to class files, add an archive or a JAR file, or remove a JAR file. There areseveral cases:4 If you need to edit the XML for classes in the file system (that is, not in a JAR file),you must add that path to the classpath using the Add Path button.5 Classes in the directory containing the META-INF directory are on the classpath bydefault.6 If your JAR has dependencies on another JAR, you must add it to the JAR'sclasspath.7 You may also add specific drivers to the classpath for the Test button on the JDBC1 Datasource panel and the Get Metadata button on the CMP 1.1 panel.8 Click OK when you're finished.Changing bean informationTo change bean information, use the following steps:1 Start the DDEditor and open a descriptor file.2 Select the bean in the Navigation pane.A detailed description of the bean appears in the Main pane. Use the tabs at thebottom of the panel to view or edit bean information. (See the following sectionsfor details.)9-24 User’ s Guide

Enterprise bean informationEnterprise bean informationThis section describes the type of information you can create and store for enterprisebeans in the deployment descriptor file.General TabUse the General panel to enter or change general information about the enterprisebean (EJB 1.1 or 2.0). This information includes:• Bean Class: The fully-qualified name of the Java class that implements the bean'sbusiness methods. This information must be specified.• Home Interface: The fully-qualified name of the enterprise bean's home interface.This information must be specified.• Remote Interface: The fully-qualified name of the enterprise bean's remoteinterface. This information must be specified.• Local Home Interface: The fully-qualified name of the enterprise bean's localhome interface (for beans in the same process). This information must be specified.• Local Interface: The fully-qualified name of the enterprise bean's local interface(for beans in the same process). This information must be specified.• JNDI Name: The JNDI name of the enterprise bean's home interface.• Local Home JNDI Name: The JNDI name of the enterprise bean's local homeinterface.• Description: A summary of the bean's purpose and function. This information isoptional.For Session beans, the General panel also includes the following:• Session Type: Specifies whether the enterprise bean is Stateless or Stateful.• Transaction Type: Specifies whether Transaction Policies are set by the bean orthe Container.• Timeout: The timeout limit applied to transactions on Stateful beans.For Entity beans, the General panel also includes the following:• Primary Key Class: The fully-qualified name of the Entity bean's primary keyclass. The primary key class must be specified.• Reentrant: A check mark indicates the bean is reentrant. Borland recommends youavoid making a bean reentrant in order to avoid unintended multithreading.The reentrant element dictates whether the bean can call itself through anotherbean. For example, a given bean A is reentrant if it calls bean B which then callsback on bean A. This a case of multithreading, but it is really only one path thatloops back on itself.If your bean doesn't call itself through another bean set this value to ”False” byleaving the Reentrant box for entity beans unchecked to avoid unintendedmultithreading. If you want to support reentrant behavior set it to ”true” byUsing the Deployment Descriptor Editor 9-25

Enterprise bean informationNotechecking the Reentrant box for entity beans so that the container will allow twothreads to run inside a bean at once.You should take special care if you are declaring an entity bean reentrant. Thecritical issue is that the Container can not generally distinguish between a(loopback) call within the same transaction and a concurrent invocation (in thesame transaction context) on the same entity bean.• Persistence Type: Select either ”container” or ”bean” from the drop-down list.Environment panelInformation in the Environment panel is used in setting EJB environment attributes/properties. Properties define how the EJB operates within a particular environment.Setting the properties in this panel allows you to customize the bean's business logicwhen the bean is assembled or deployed without accessing or changing the bean'ssource code.Each enterprise bean defines its own set of environment entries. All instances of anenterprise bean share the same environment entries. Enterprise bean instances arenot allowed to modify the bean's environment at runtime.To add an environment entry:1 Click Add to create a new entry.A new, blank row appears in the panel.2 Enter a property in the Property column and a property value in the Valuecolumn.3 Choose a property type from the Type drop-down menu.Property types can be: String, Integer, Boolean, Byte, Short, Long, Double,Character, and Float.4 Continue to add environment entries as desired.Some things to remember about environment entries include:• The bean provider must declare all the environment entries accessed from theenterprise bean's code.• If the bean provider includes a value for the environment entry, the value can bechanged later during assembly or deployment.• During assembly, you can modify the values of the environment entries set by thebean provider.• During deployment, you must ensure that the values of all environment entriesare set to meaningful values.9-26 User’ s Guide

Enterprise bean informationEJB References panelThe EJB References panel lists all the enterprise bean references to the homes of otherenterprise beans.Each EJB Reference describes the interface requirements that the referencingenterprise bean has for the referenced enterprise bean.Refer to EJB References above.Security Identity panelThe security identity panel (EJB 2.0)allows you to control security propagation byspecifying your bean security identities when calling methods from other beans.When you call a method in EJB, the container propagates your security informationby implicitly passing your security context within the stubs and skeletons. Forexample, you may have a client that is authenticated with the proper securityidentity. If the client calls bean A which in turn calls bean B, you may want to controlwhether or not bean B receives the client's security identity or whether it receives adifferent principal.This panel provides two options for bean security identity:• Use caller identity• Run asThe following examples demonstrate usage for both options.Use caller identity. You can control how security information is propagated in yourdeployment descriptor. The following code example takes the bean's securityidentity and propagates it to all the other beans it calls:......AccountAdministrationexamples.AccountAdministrationHome.........To specify security identity for your bean, as shown above, check the ”SpecifySecurity Identity” checkbox, enter a description for your identity (if desired), andselect the Use caller identity identity type from the drop-down list.Using the Deployment Descriptor Editor 9-27

Enterprise bean informationNoteRun as. In comparison to the above example, you may want your bean to justpropagate a role like ”admin” to all other beans it calls. In this case you set up thebean's security identity to run as a pre-defined . The following is a codeexample for Run as:......AccountAdministrationexamples.AccountAdministrationHome...admin......This role is for people authorized to perform account administration.admin...If you choose this security identity option, you also must choose a run-as role fromthe Run drop-down list that appears. Roles are defined on the Security Role Referencestab. Roles are created in the navigation pane under ”Security Roles”.Many beans do not require a security identity. Those that do not should leave the”Specify Security Identity” checkbox blank.9-28 User’ s Guide

Enterprise bean informationFigure 9.5Security Identity PanelSecurity Role References panelThe Security Role References panel lists all the enterprise bean's declared securityroles and links to its ”abstract security role”. The deployer might be assemblingbeans from different sources, bean developers, who may have declared security rolesdifferently. The deployer uses the Security Role References panel to link the declaredsecurity role references to specific security roles defined by the application assembleror deployer.For example, a specific bean developer may have defined the role-name forAccountAdministration as administrator while the deployer uses admin as the role-name.In this case the deployer will have to generate the security role that the applicationwill use. Using the element solves this, as shown in the following codesample.......AccountAdministrationexamples.AccountAdministrationHome...This role is for people authorized to perform account administration.administratoradmin...Using the Deployment Descriptor Editor 9-29

Enterprise bean information...This role is for people authorized to perform account administration.admin...To create security role reference links (links are the names of the security roles for thedeployment of the application), you must first create a security role. To do this, referto “Creating a security role” on page 9-36.After deployment roles are created, they should appear under the Link field in theSecurity Role References Panel.To link this role to the name of the security role specified by the bean developer,enter the name specified by the bean developer in the Role field. Enter a descriptionof the role if desired.Figure 9.6Security role references panelInformation in the panel includes:• Description: This is an optional field that describes the Security Role.• Role: This is the name of the Security Role specified by the bean developer.• Link: This is the name of the Security Role used when the application is deployed.Typically, this role is defined by the application assembler or deployer to work ina specific operating environment.9-30 User’ s Guide

Enterprise bean informationSome things to remember about Security Role references include:• The Security Role references used by the enterprise bean is a ”generic” name thatmust be mapped to a specific operating environment.• You can add or remove rows as necessary.EJB Local References Panel (EJB 2.0 only)The EJB Local References panel lists all the enterprise bean references to the homes ofother enterprise beans within a single archive.Each EJB Local Reference describes the interface requirements that the referencingenterprise bean has for the referenced enterprise bean. The reference contains:• Description: A brief description of the bean that is referenced. This information isoptional.• Name: The name of the referenced bean. The tool tip information shows what youuse to access the Name in code.• IsLink: If checked, there is a link to a local enterprise bean and the following fieldsare filled in and read-only: Type, Home, and Remote. If unchecked, reference is toan enterprise bean outside the JAR file and you must fill in Type, Home, andRemote.• Link: Links the EJB Reference to the target enterprise bean. The Link value is thename of the target enterprise bean. This information is optional.• Type: The expected type of the referenced bean.• Local Home: The expected Java type of the referenced bean's home interface.• Local: The expected Java type of the referenced bean's local interface.• JNDI Name: The JNDI name of the referenced bean.Resource References panelThe Resource References panel lists all the enterprise bean's resource factoryreferences. This enables the application assembler and/or bean deployer to locate allreferences used by the enterprise bean.Information in the panel includes:• Description: A description of the resource reference. This information is optional.• Name: The name of the environment entry used in the enterprise bean's code.• Type: The Java type of the resource factory expected by the enterprise bean's code.This is the Java type of the resource factory, not the Java type of the resource. Thetypes available are:• javax.sql.DataSource• java.net.URL• javax.mail.Session• javax.jms.QueueConnectionFactoryUsing the Deployment Descriptor Editor 9-31

Enterprise bean information• javax.jms.TopicConnectionFactoryThe Deployment Settings (parameters) you can specify depend upon the Javatype selected.• Authentication: An Application authentication indicates that the enterprise beanperforms the resource sign-on programmatically. A Container authenticationindicates that the Container signs on to the resource (on behalf of the webapplication) based on the principal mapping information supplied by thedeployer.• Sharing Scope: The element specifies whether connectionsobtained through the given resource manager connection factory reference can beshared. The values of this element must be either or . Thedefault is Shareable.Message-Driven Bean PanelEJB 2.0 architecture supports Message-Driven Beans (MDBs). If you choose to createa new message-driven bean or descriptor for a message-driven bean, you will see theMessage-Driven Bean panel when you click on the bean in the Navigation pane. Thispanel allows you to set the following message-driven bean information:• Transaction Type: whether or not the transaction is bean- or container-managed.If you select bean-managed transactions, you will also have to select one of thefollowing acknowledge modes:• Auto-acknowledge: automatically acknowledges a client's receipt of a messagewhen it has either successfully returned a call to receive or the MessageListener ithas called to process the message successfully returns.• Dups-ok-acknowledge: This option instructs the session to lazily acknowledgethe delivery of messages, likely resulting in duplicate messages if JMS fails. It hasthe benefit of reducing session overhead but at the cost of duplicating messages.• Message Selector: string of rules used by the client to specify only the messagesit's interested in, by header. The syntax of the rules is based on a subset of theSQL92 conditional expression syntax. See the JMS Specification from SunMicrosystems for details.• Destination: the JMS destination from which the message-driven bean instanceconsumes messages.• Destination Name: the JNDI name of the queue or topic to which the messagedrivenbean listens.• Destination Type: specifies whether the destination is a queue, topic, orunspecified; javax.jms.Queue, javax.jms.Topic, or Not Specified.• Connection Factory Name: JNDI name of the connection factory used to establisha connection with the message broker.• Initial Pool Size: specifies the initial number of message-driven bean instancesthat the container should create immediately after deployment.9-32 User’ s Guide

Container transactions• Maximum Pool Size: specifies the maximum number of message-driven beaninstances that can be created and kept in the message-driven bean instance pool.• Wait Timeout: specifies the number of seconds before timeout.Figure 9.7Message-Driven Bean panelContainer transactionsEnterprise beans that use container-managed transactions must have the TransactionPolicies set by the Container. The DDEditor enables you to set container-managedTransaction Attributes and then associate these attributes with methods in theenterprise bean's home and remote interface.Adding a container transactionTo add a container transaction:1 In the navigation panel of the DDEditor, click on the enterprise bean so that all ofits components are shown in the hierarchical tree.2 In the navigation panel, click on Container Transactions for that enterprise bean.The Properties panel appears for the transaction.Using the Deployment Descriptor Editor 9-33

Container transactionsFigure 9.8New container transaction3 Enter a Description for the transaction.4 Use the menu in the Interface column to choose either the home, remote, local, orlocalHome interface for the bean, or use * to specify all.5 Use the menu in the Method column to select methods. This menu lists allmethods for the interface specified in the previous column. Choose a specificmethod, or use * to specify all methods.6 For each Interface and Method combination, select a Transaction Attribute fromthe menu.Transactions supported include:Table 9.1Transaction attributesAttribute Syntax DescriptionSupports TX_SUPPORTS The bean is invoked with thesame Transaction Policy as theclient, if it has one. Otherwise,no transaction context is set.Not Supported TX_NOT_SUPPORTED The bean is invoked without atransaction context.Never TX_BEAN_NEVER An enterprise bean neverinvokes the User Transactioninterface (javax.jts).Required TX_REQUIRED The bean is invoked with thesame Transaction Policy as theclient, if it has one. Otherwise,the Container starts a newtransaction before invoking amethod on the bean. TheContainer commits thetransaction upon returningfrom the method.9-34 User’ s Guide

Table 9.1Transaction attributes (continued)Adding security roles and method permissionsAttribute Syntax DescriptionRequires New TX_REQUIRES_NEW The bean requires a newtransaction. The bean isalways invoked in a newtransaction.Mandatory TX_MANDATORY The bean requires atransactional context. The beanis invoked with the sameTransaction Policy as theclient, if it has one. Otherwise,an exception(javax.transaction.TransactionRequiredException) is thrownto the client.Adding security roles and method permissionsThe DDEditor enables you to create or edit security roles in the deploymentdescriptor. After Security Roles are created, you can then associate methods in theenterprise bean's home and remote interface with these roles, thus defining thesecurity view of the application. In addition you canAbout Security RolesSecurity roles are encountered in EARs, WARs and EJB JARs. They are intended to belogical roles that can be used in a variety of security environments. The advantage tousing security roles is not having to hard-code specific identities into the beans sinceeach environment has its own list of identities. This also makes it possible for you tomodify access control without recompiling bean code. During deployment securityroles are mapped to specific user groups and/or user accounts defined in theoperating environment.This section describes how to use the DDEditor to create security roles and assignenterprise bean method permissions to the roles. Defining security roles in thedeployment descriptor is optional.Using the Deployment Descriptor Editor 9-35

Adding security roles and method permissionsCreating a security roleNoteTo create a security role in the deployment descriptor:1 In the navigation panel of the DDEditor, open the EAR, WAR or EJB JAR to whichyou want to assign roles.2 Right-click the Security Roles folder and select New Role from the context menu.A dialog box appears.3 Enter the name of the new Security Role and click OK.4 The new Security Role appears in the Navigation pane.To create a security role:1 Select the Security Role in the Navigation pane.The Properties panel appears for the role. The information includes:Deployment role. The standard security-role-ref element defines an alias to thesecurity-role element allowing applications to refer to roles hard-coded in thebean code. Using role-refs allows deployers to change roles by adjusting the rolerefsrather than having to update application code.Similarly, the deployment-role element is another alias for the security-role element.It allows users to maintain roles in the deployment descriptor independently ofdeployment roles that are defined in the authorization domain. Again, this allowsdeployers to map security roles, by using the deployment-role element, to existingroles defined in the appropriate authorization domain without changing thestandard deployment descriptor.It is not necessary to use the deployment-role element to bind roles to theauthorization domain. If there is no deployment-role defined for a security-role, thesecurity-role is assumed to be defined in the authorization domain.The deployment-role element is a Borland-specific element and appears in theVendor XML tab.Description. This is an optional field, but enables the bean deployer to betterunderstand the intent of the role.2 Enter a Deployment Role.3 Enter a Description for the role.9-36 User’ s Guide

Assigning method permissionsFigure 9.9Security roles properties panelAssigning method permissionsOnce Security Roles are defined, you can specify which methods in the home andremote interface of an enterprise bean the Security Role is allowed to invoke. This isdone using method permissions.If the application assembler or bean developer defines security roles for theenterprise bean in the JAR file, they can specify the methods of the home andcomponent interfaces that each security role is allowed to invoke. However, you arenot required to associate a security role with methods in a bean's home or remoteinterface. Therefore, any security roles defined in the deployment descriptor are notallowed to invoke these methods unless associated with security roles in the bean'sinterface(s).Some things to remember about method permissions:• Each method-permission element includes a list of one or more security roles (only ifthere is ”by Role” access) and a list of one or more methods. All listed securityroles are allowed to invoke all listed methods. Each security role in the list isidentified by the role-name element, and each method (or set of methods) isidentified by the method-name element.• A security role or method may appear in multiple method-permission elements.• You can specify that some methods should not be checked for authorization priorto invocation by the Container. This is done by using the unchecked element insteadof a role name in the method-permission element which indicates that a methodwon't be checked for authorization.• If the method permission specifies both the unchecked element for a given methodAND one or more security roles (if there are conflicting permissions set), themethod won't be checked for authorization.Using the Deployment Descriptor Editor 9-37

Assigning method permissionsNote• You can use the exclude-listelement to indicate the set of methods that will not becalled. In this case, you should configure the enterprise bean's security such thatno access is permitted to any method contained in the exclude-list.• If a given method is specified in both the exclude-list element and in the methodpermission, you should configure the enterprise bean's security such that noaccess is permitted to the method.• If you have multiple methods with the same name but that take differentparameters, you can set permissions to distinguish between the two using themethod-params element. This must be edited manually, directly in the XML.Multiple methods with the same name but with different parameters are listed inthe Method pull-down menu. For example, in the SavingsAccount bean of thebank_beansexample, there are two create methods listed in the Method pull-downmenu, create and create(String, float).To assign method permissions:1 In the Navigation pane in the DDEditor, open the bean to which you want toassign method permissions.2 Double-click Method Permissions from the bean's hierarchical menu.3 In the Properties panel, enter a description. This is optional.4 Click Add.5 Select an interface in the Interface column to choose either the local home, local orremote interface for the bean, or select * to specify all.6 Select a method from the Methods pull-down menu. This menu lists all methodsfor the interface(s) specified in the previous column. Choose a specific method, orselect * to specify all methods.7 Select a permissions level from the Access pull-down menu. You can choose from:• By Role. Choose one or more security role to specify which roles are allowed toinvoke your selected method(s).• Unchecked. This specifies that some methods will not be checked forauthorization prior to invocation by the Container. This element is used insteadof a role-name element in the method permission.• Excluded. This is used to specify the exclude-list element, which specifiesmethods that will not be called.8 Select which role you want associated with the method.9-38 User’ s Guide

Adding CMP 1.1 information9 Continue to specify beans and methods as desired.Figure 9.10 Specifying Method PermissionsAdding CMP 1.1 informationNoteNoteFor entity beans, set persistence type to CMP 1.1 in the General tab to see the CMPnode in the Navigation pane. To add container-managed persistence information:If you change the CMP version (1.1, 2.0), all previous CMP changes will be lost.1 In the Navigation panel of the DDEditor, expand the enterprise bean so that all ofits components are shown in the hierarchical tree.2 Select the CMP 1.1 element to display its properties in the ”CMP 1.1” pane.You can work with multiple tables and multiple columns.Figure 9.11CMP 1.1 fieldsUsing the Deployment Descriptor Editor 9-39

Adding CMP 1.1 informationFor beans with container-managed persistence (1.1), the following additionalinformation is included to enable you to map fields in the bean to columns in adatabase table:• Get Metadata: Queries the database to get a list of column names and types shownin a ”Container Managed Fields” table.• CMP Description: This is an optional field that describes the container-managedpersistence.• Table(s): The name of the database table(s) referenced by the bean.Container Managed Fields• Description: This is an optional field that describes a container-managed field.• isCMP: A check mark indicates the field is container-managed.• isPK: A check mark in the box indicates that this is a primary key. It also indicatesthe type of primary key class matches the field's class.• Field Type: The data type of the field. If Type is a collection or subclass ofEJBObject, there is an EJB Reference associated with it. In other words, Type refersto a foreign key. Collection foreign keys can match any EJB reference. Otherwise,the type must match the home interface of the EJB reference.• Field name: Name of field in an entity bean.• Column name(s): You can map compound fields in the bean (for example,location.street) to columns in the database table. You can either map the root field(for example, location) or the sub fields (for example, location.street), but not both.• Column type: The column's type, for example, CHAR(1)NOT NULL.• EJB Reference: If the field type is an EJB class, a menu appears with a list of EJBReferences to select. These references are set in the EJB References panel. ”None”is a valid entry.The panel displays the primary key class name, which you can't change. In theCMP Description field, you can enter optional text describing the bean.The DDEditor uses JDBC to obtain metadata on existing tables. You can hook upentity beans to existing tables. For example, you might purchase a third-partyenterprise bean and want to use it with a table in your database. To populate boththe Column Name and Column Type fields, click the Get Metadata button and themetadata is retrieved.Finders panelThe Finders panel only appears for EJB entity beans with container-managedpersistence. It specifies the WHERE clause used by the CMP bean to execute findermethods defined by the bean.Information includes:9-40 User’ s Guide

Adding CMP 2.0 information• Method: The finder method name and a list of all arguments, for example,findAccountsLargerThan(float balance).• Where Clause: Specifies a SQL WHERE clause used by the Container to retrieverecords from the database, for example, balance > :balance.• Load State: A check mark enables the Container to preload all Container-managedfields whenever a FIND operation occurs.Adding CMP 2.0 informationFor information on CMP 2.0 refer to “The EJB Designer” on page 9-42. Forinformation on CMP 2.0 in the Borland Enterprise Server, refer to "Entity Beans andCMP 2.0 in Borland Enterprise Server" in the Developer's Guide.Adding a new datasourceNoteThe DDEditor enables you to specify a new data source for Entity beans andContainers and set the isolation level for the data transactions.To add a new datasource:1 Select an EJB JAR file in the Navigation pane and open it.2 Right-click the JDBC 1 Datasources folder and select New Datasource from thecontext menu.A dialog box appears.3 Enter the JNDI name of the new data source and click OK. A new data sourceappears in the Navigation pane.4 Double-click the datasource.The Properties panel for the data source appears.5 Enter information for the new data source. The information includes:URL. The URL is the location of the datasource.User name and password. These may be required to access the source.Driver class name. Class name of the JDBC driver. Clicking on ellipses opens awindow with listed drivers.Test Connection button. This tests the connection to the datasource.A connection to the database will fail if the driver is not on your classpath. Youmust add the driver to the classpath using the Set Classpath command.The data source is defined by a data source name, the URL location of the datasource, and (if required) a user name and password to access the source. The panelalso includes the class name of the JDBC driver and JDBC properties.Using the Deployment Descriptor Editor 9-41

The EJB Designer6 Choose an Isolation Level from the pop-up menu. See the following section fordetails.Isolation levelsIsolation level refers to the degree to which multiple, interleaved transactions areprevented from interfering with each other in a multiuser database. Possibletransaction violations include:• Dirty Read: Transaction t1 modifies a row. Transaction t2 then reads the row.Now t1 performs a rollback and t2 has seen a row that never really existed.• Non-Repeatable Read: Transaction t1 retrieves a row. Then transaction t2 updatesthis row and t1 retrieves the same row again. Transaction t1 has now retrieved thesame row twice and has seen two different values for it.• Phantoms: Transaction t1 reads a set of rows that satisfy certain search conditions.Then transaction t2 inserts one or more rows that satisfy the same searchcondition. If transaction t1 repeats the read, it will see rows that did not existpreviously. These rows are called phantoms.The transaction isolation levels set in the deployment descriptor are defined based onthe permitted violations defined above.Table 9.2Isolation level attributesAttribute Syntax DescriptionUncommittedCommittedRepeatableSerializableTRANSACTION_READ_UNCOMMITTEDTRANSACTION_READ_COMMITTEDTRANSACTION_REPEATABLE_READTRANSACTION_SERIALIZABLEAllows all three violations.Allows Non-Repeatable Readsand Phantoms, but does notallow a Dirty Read.Allows Phantoms, but not theother two violations.Does not allow any of thethree violations.The EJB DesignerThe DDEditor's implementation of the EJB Designer is primarily to facilitate the (O/R) mapping of CMP 2.0 entity beans' persistence schemas to a database, and forsetting Borland-specific entity bean CMP properties for deployment. Manyproperties are disabled in the DDEditor's implementation of the EJB Designer as theyrequire code change and must be changed in the source.To use the EJB Designer effectively, you should have a schema already imported intothe DDEditor in order to edit the CMP 2.0 properties. If you do not have it set upalready, or do not have the vendor-specific XML imported, you will have to createand edit the table properties manually.9-42 User’ s Guide

The EJB DesignerFor information on the full implementation of the EJB Designer, refer to BorlandJBuilder documentation, Enterprise Application Developer's Guide.CMP properties you can edit are:Table properties• Table names• Column names• Primary key values• Table references (foreign key relationships)• Cross table references (intermediate table)Methods• Finder method query stringsBean properties• Abstract schema nameEntity CMP properties• ejb.invalidateFinderCollectionAtCommit value• ejb.maxBeansInCache value• ejb.cacheCreate value• ejb.maxBeansInPool value• ejb.transactionCommitModeSession bean• Session bean type• Session bean container transaction typeEJB Designer and CMP 2.0 general informationThe Borland Enterprise Server's EJB Container implements both container-managedpersistence (CMP) for EJBs implementing either the EJB 1.1 and/or EJB 2.0specifications. The bean provider designs persistence schemas for entity beans,determines the methods for accessing container-managed fields and relationships,and defines these in the beans' deployment descriptors. The deployer then maps thepersistence schema to the database and creates any other necessary classes for thebeans' maintenance.Using the Deployment Descriptor Editor 9-43

The EJB DesignerContainer-created tablesYou can instruct the Borland EJB Container to automatically create tables forcontainer-managed entities based on the entity's container-managed fields, which aredefined in the entity bean deployment descriptors. Because table creation and datatype mappings vary among vendors, you must specify the JDBC database dialect inthe deployment descriptor to the Container. For all databases (except JDataStore), ifyou specify the dialect, the Container automatically creates tables for containermanagedentities for you. The Container will not create these tables unless youspecify the dialect.Table mapping for CMP 2.0 is accomplished using the Borland-specific ejbborland.xmldeployment descriptor. This descriptor is a companion to the ejb-jar.xmldescriptor described in the EJB 2.0 specification. Borland uses the XML tag

The EJB DesignerFigure 9.12Editing finder methodsTable Reference EditorYou can create relationships between EJB 2.0 entity beans. For example, if you havean EMPLOYEE table, you might want to create a relationship that reflects whichemployees are assigned to which project(s). Relationships are created when entitybeans are created. The DDEditor's EJB Designer allows you to edit tablerelationships.To create relationships between EJB 2.0 entity beans using the EJB Designer, refer tothe Borland JBuilder Enterprise Application Developer's Guide documentation.By default, the relationships are created by looking for columns (or fields) with thesame name in the two tables you are connecting. Often, the two tables won't have acommon column name. You must therefore specify how the relationship is created.NoteUsing the Table Reference Editor to specify table relationshipsIf two tables do not have common column names, you must connect the columns youwant to use to create the relationship by drawing a line. For example, if the EMPLOYEEtable has a column called EMP_NO, and the EMPLOYEE_PROJECT table has a column calledPROJ_ID, you can draw a line between the two columns to create the relationship.The links drawn in represent the foreign key relationships between tables.To create a table relationship:1 In the DDEditor's EJB Designer, click on the name of entity bean representation inthe EJB Designer.2 In the Bean properties panel, click the Add button in the table references section.The entity bean's table and columns should be present in the left menu.3 Select a table from the drop-down list on the right that you want the selectedentity bean's table to reference.Using the Deployment Descriptor Editor 9-45

The EJB Designer4 Click and drag to draw links between the columns of the table on the left and thetable on the right.Once you've created the relationship(s), click OK.Figure 9.13 Specifying table referencesMany-to-many relationshipsFor many-to-many relationships you need a third table to make the connectionbetween two tables. For example, you might have an EMPLOYEE table that includes acolumn named EMP_NO. You might also have a PROJECT table with a column namedPROJ_ID. By themselves the two tables may not have any columns you can use tocreate a relationship directly. If you have an EMPLOYEE-PROJECT table that consists oftwo columns, EMP_NO and PROJ_ID, you can create a relationship between the EMPLOYEEand PROJECT tables. In this case, you would use the ”Add Cross Table” function in theTable Reference Editor.To use the Add Cross Table function to create a many-to-many relationship:1 In the DDEditor's EJB Designer, click on the name of entity bean representation inthe EJB Designer.2 In the Bean properties panel, click the Add button in the table references section.The entity bean's table and columns should be present in the left menu.3 Select a table from the drop-down list on the right that you want the selectedentity bean's table to reference.4 To add a cross table (an intermediate table used to related two unrelated tables),click the Add Cross Table button.5 From the drop-down list that appears between the two tables, select the new tablethat contains the columns to make the connection between the two.6 Click and drag between the columns to make the appropriate connections.9-46 User’ s Guide

Borland-specific deployment descriptorsFigure 9.14Using a cross table for many-to-many relationships7 Click OK when you are done with the cross table.A new field will appear in the Bean properties panel of your referenced bean in theTable References window.This will appear in the Vendor XML tab as a Borland-specific descriptor element using the element(s) left-table, and .Borland-specific deployment descriptorsIn addition to the deployment descriptors which follow the Sun DTD specifications,Borland implements proprietary deployment descriptors in Borland DTDs. TheBorland-specific descriptors are XML files which contain a set of properties thatdescribe how the container deploys and archive or application.The Borland-specific descriptors (XML files) are viewed and edited on the Vendortab, which appears at the top level archive file.Using the Deployment Descriptor Editor 9-47

Borland-specific deployment descriptorsThe Borland DTDsThe Borland-specific deployment descriptors are part of Borland's DTDs. The DTDsare:• application-client_1_2-inprise.dtd• application-client_1_3-borland.dtd• application_1_2-inprise.dtd• application_1_3-borland.dtd• connector_1_0-borland.dtd• ejb-inprise.dtd• ejb-jar_2_0-borland.dtd• web-app_2_2-inprise.dtd• web-app_2_3-borland.dtdThe following tables list the elements, additional or subordinate elements, theirdescription and their location in the DDEditor for the newest EAR (application_1_3-borland.dtd), JAR (ejb-jar_2_0-borland.dtd) and WAR (web-app_2_3-borland.dtd)descriptors.Table 9.3Application 1.3-Borland DTDElement Additional Elements Description DDEditor Locationapplicationmodulemodule, env-def,property,authorizationdomain,security-roleconnector | ejb | java| web | hostsSpecifies theapplication, itsmodules (EJBs, JARs,etc.), environmentdefinitions whichspecifies the URI of aenf-def relative to thetop level of theapplication package,environmentproperties for theapplication, such asname, type and value,authorization domainfor the application,and defined securityroles for theapplication.Specifies themodule(s) beingdefined in theapplication (EJB JARs,WARs, connectorsand hosts.Application level(EAR) Vendor XMLtab.Application level(EAR) Vendor XMLtab.9-48 User’ s Guide

Table 9.3connector n/a Specifies theconnector(s) beingdefined in theapplication.propertyApplication 1.3-Borland DTD (continued)prop-name, proptype,prop-valueBorland-specific deployment descriptorsElement Additional Elements Description DDEditor LocationSpecifies applicationenvironmentproperties.web web-uri Specifies the WARmodules' web URIs,such as”helloweb.war” in theapplication.ejb n/a Specifies EJB JARmodules in theapplication.env-def n/a Specifies the URI of anenvironmentdefinition relative tothe top levelapplication package.hosts n/a Host is a string withsyntax |. Anempty value meansthat all servers willhost the module in allcontainers that canhost that type ofmodule. If just isspecified then allcontainers in theserver that can host amodule of that typewill host the module.A value of '*' for specifiesall servers.Application level(EAR) Vendor XMLtab.Application level(EAR) Properties tab.Application level(EAR) Context Rootstab.Application level(EAR) Vendor XMLtab.Application level(EAR) Vendor XMLtab.Application level(EAR) Vendor XMLtab.Using the Deployment Descriptor Editor 9-49

Borland-specific deployment descriptorsTable 9.3authorization-domain n/a Specifies whichauthorization domainis used for the webapplication. Becausemultipleauthorizationdomains can bedefined in anapplication server,you must specify theone for the webapplication. Theauthorization domainspecified must be oneof the domainspreviously defined.security-roleTable 9.4role-name,deployment-roleEJB JAR 2.0-Borland DTDMaps the roles used inthe application to thereal roles defined inthe application serverby specifying the (rolename, deploymentrole). Security rolesare configured inSecurity Roles innavigation pane ofDDEditor.Application level(EAR) General tab.Security Roles tabElement Additional Elements Description DDEditor Locationejb-jarenterprise-beansApplication 1.3-Borland DTD (continued)Element Additional Elements Description DDEditor Locationenterprise-beans,datasourcedefinitions,tableproperties,relationships,authorizationdomain,property,assembly-descriptorsession|entitiy|entitye-drivenSpecifies generalstructural andassembly descriptorinformation for EJBJAR modules.Specifies bean types inthe JAR.JAR level VendorXML tab.Bean level, source.9-50 User’ s Guide

Table 9.4Borland-specific deployment descriptorsElement Additional Elements Description DDEditor Locationsessionejb-name, bean-homename,bean-localhome-name,timeout,ejb-ref, ejb-local-ref,resource-ref, resourceenv-ref,propertySpecifies generalinterface informationfor session beans andvarious references forsession bean.bean level General tab(interfaces andtimeout), EJBReferences tab (ejbref),EJB LocalReferences tab (ejblocal-ref),ResourceReferences tab(resource-ref),Resource Env Refs tab(resource-env-ref) andProperties tab(property).entitymessage-drivenpoolejb-refEJB JAR 2.0-Borland DTD (continued)ejb-name, bean-homename,bean-localhome-name,ejb-ref,ejb-local-ref, resourceref,resource-env-ref,cmp-info | cmp2-info,propertyejb-name, messagedriven-destinationname,connectionfactory-name,pool,ejb-ref, ejb-local-ref,resource-ref, resourceenv-ref,propertymax-size, init-size,wait-timeoutejb-ref-name, jndinameSpecifies generalinterface information,container-managedpersistence (1.0 and2.0) and variousreferences for entitybeans.Specifies generalmessage-driven beaninformation, messagequeue or topicinformation andvarious references forentity beans.Specifies maximumpool size, initial poolsize and wait timeoutsfor message-drivenbeans.Specifies a JNDI nameto associate with theEJB reference name.entity bean levelGeneral tab(interfaces, cmp-info |cmp2-info), EJBReferences tab (ejbref),EJB LocalReferences tab (ejblocal-ref),ResourceReferences tab(resource-ref),Resource Env Refs tab(resource-env-ref),and Properties tab(property).message-driven beanlevel Message-DrivenBean tab (destinationname, connectionfactory name, poolsizes), EJB Referencestab (ejb-ref), EJB LocalReferences tab (ejblocal-ref),ResourceReferences tab(resource-ref),Resource Env Refs tab(resource-env-ref),and Properties tab(property).message-driven beanlevel Message-DrivenBean tabbean level ReferencestabUsing the Deployment Descriptor Editor 9-51

Borland-specific deployment descriptorsTable 9.4ejb-local-refresource-refresource-env-refejb-ref-name, jndinameres-ref-name, jndiname,cmp-resourceresource-env-refname,jndi-nameSpecifies a JNDI nameto associate with theEJB local referencename.Specifies a JNDI nameto associate with theresource reference orcmp resource.Specifies a JNDI nameto associate with theresource environmentreference.datasource-definitions datasource Specifies a JNDI nameto associate with adatasource.datasourcejdbc-propertycmp-infojndi-name, url,username, password,isolation level, driverclass-name,jdbcproperty,propertyprop-name, propvaluedescription, databasemap,finderSpecifies datasourceinformation.Specifies JDBCdatasource properties.Specifies containermanagedpersistenceproperties (mappingand finders).database-map table, column-map Specifies databasemapping propertiesfor tables andcolumns.findercolumn-mapconnection-factorynamemessage-drivendestination-nameEJB JAR 2.0-Borland DTD (continued)Element Additional Elements Description DDEditor Locationmethod-signature,where-clause, loadstatefield-name, columnname,column-type,ejb-ref-namen/an/aSpecifies findermethods.Specifies columnproperties in adatabase.Specifies JNDI nameof the connectionfactory used toestablish a connectionwith the messagebroker.Specifies the JNDIname of the queue ortopic to which themessage-driven beanlistens.bean level LocalReferences tabbean level ResourceReferences tabbean level ResourceEnv Refs tabJDBC datasourceslevel General tabJDBC datasourceslevel General tab andProperties tab(property)JDBC datasourceslevel Properties tabnot set in DDEditor,must be done in codenot set in DDEditor,must be done in codecan be edited inDDEditor EJBDesignercan not be edited inDDEditormessage-driven beanlevel Message-DrivenBean tabmessage-driven beanlevel Message-DrivenBean tab9-52 User’ s Guide

Table 9.4EJB JAR 2.0-Borland DTD (continued)Borland-specific deployment descriptorsElement Additional Elements Description DDEditor Locationmax-size n/a Specifies themaximum number ofmessage-driven beaninstances that can becreated and kept inthe message-drivenbean instance pool.init-size n/a Specifies the initialnumber of messagedrivenbean instancesthat the containershould createimmediately afterdeployment.wait-timeout n/a Specifies the numberof seconds beforetimeout.cmp-resource n/a Specifies a name toassociate with a CMPresource.method-signature n/a Specifies containermanagedpersistenceproperties (mappingand finders).where-clause n/a Specifies a SQL WHEREclause used by theContainer to retrieverecords from thedatabase, for example,balance > :balance.load-state n/a Specifies theContainer enabled topreload all Containermanagedfieldswhenever a FINDoperation occurs.field-name n/a Specifies name of fieldin an entity bean. Thiswill correspond tocolumn-name.column-name n/a Specifies columns inthe database table,usually that are fieldsin the bean (forexample,location.street).message-driven beanlevel Message-DrivenBean tabmessage-driven beanlevel Message-DrivenBean tabmessage-driven beanlevel Message-DrivenBean tabbean level ResourceReferences tabJDBC datasourceslevel Properties tabedited in DDEditorEJB Designer, in thefindMethod of the beanedited in DDEditorEJB Designer, in thefindMethod of the beancannot be set inDDEditor EJBDesigneredited in DDEditorEJB Designer byclicking on bean fieldsor by editing in theDatasourcesnavigation pane.Using the Deployment Descriptor Editor 9-53

Borland-specific deployment descriptorsTable 9.4column-type n/a Specifies column'stype, for example,CHAR(1)NOT NULL.table n/a Specifies a tableschema in a database.table-propertiescmp2-infotable-name, columnproperties,propertycmp-field, table-name,table-refSpecifies theproperties of a table ina database, such asgetPrimaryKeyAfterInsertSql anduseGetGeneratedKeys.Specifies CMP 2.0fields for EJBsrelationships ejb-relation Specifies name of fieldin an entity bean. Thiswill correspond tocolumn-name.table-refleft-tableright-tablecross-tableEJB JAR 2.0-Borland DTD (continued)Element Additional Elements Description DDEditor Locationleft table, cross-table,right-tabletable-name, columnlisttable-name, columnlisttable-name, columnlistSpecifies references orlinks betweencolumns in tables.Links indicate foreignkeyrelationships.Specifies a table inrelation to another,wherein the tablenameand column-listelements are defined.Specifies a table inrelation to another,wherein the tablenameand column-listelements are defined.Specifies anintermediate tableused ”between” twotables, wherein thetable-name andcolumn-list elementsare defined.column-list column-name Specifies the columnswhich are to be usedin table-refs whereinthe column-name isdefined.edited in DDEditor'sDatasourcesnavigation pane byright-clicking oncolumn.edited in DDEditor'sDatasourcesnavigation pane byright-clicking on table.edited in DDEditor'sDatasourcesnavigation pane byright-clicking on table.edited in DDEditorEJB Designercannot be set inDDEditor EJBDesignerset in DDEditor EJBDesignertable-refs in DDEditorEJB Designertable-refs in DDEditorEJB Designertable-refs in DDEditorEJB Designertable-refs in DDEditorEJB Designer9-54 User’ s Guide

Table 9.4Element Additional Elements Description DDEditor Locationassembly-descriptor security-role Specifies anapplication-assemblydescriptorn/asecurity-roleEJB JAR 2.0-Borland DTD (continued)role-name,deployment-roleSpecifies a predefinedname for arole for the bean'ssecurity identity torun as.role-name n/a Specifies a table inrelation to another,wherein the tablenameand column-listelements are defined.deployment-role n/a Is a level ofindirection for thesecurity-role elementwhich allowsdeployers to mapsecurity roles, byusing the deploymentroleelement, toexisting roles definedin the appropriateauthorization domain.defined in SecurityRoles in thenavigation panedefined in SecurityRoles in thenavigation paneSecurity Roles tabFor information on the Borland-specific web application 2.3 descriptors, refer toUnderstanding the Web Edition services.Using the Deployment Descriptor Editor 9-55

9-56 User’ s Guide

10ChapterChapter10iastool command-lineutilityImportantThis section describes the iastool command-line utility that you can use to managethe Borland Enterprise Server.For documentation updates, go to www.borland.com/techpubs/bes.Using the iastool command-line toolsThe iastool utility is a set of command-line tools for managing Borland EnterpriseServer. The following table shows the command-line tools provided with the iastoolutility:Table 10.1Use...iastool command-line utilitiesTo...-compilejsp Precompile JSPs in a standalone WAR or all WARs in an EAR. For moreinformation, see “compilejsp” on page 10-2.-compress Compress a JAR file. For more information, see “compress” on page 10-3.-deploy-dumpstack-genclient-gendeployable-genstubs-info-killDeploy a J2EE module to a Partition on a Borland Enterprise Server. Formore information, see “deploy” on page 10-4.Dump the stack trace about threads running in a Partition process. For moreinformation, see “dumpstack” on page 10-7.Generate a client library. For more information, see “genclient” onpage 10-8.Generate a manually deployable module. For more information, see“gendeployable” on page 10-9.Generate a stub library. For more information, see “genstubs” onpage 10-10.Display configuration information. For more information, see “info” onpage 10-13.Kill a server, service, or Partition on a management port. For moreinformation, see “kill” on page 10-13.iastool command-line utility 10-1

Using the iastool command-line toolsTable 10.1Use...-listpartitions-listservers-listservices-merge-migrate-patch-ping-removestubs-restart-setmain-start-stop-uncompress-undeploycompilejspUse this tool to precompile JSP pages in a standalone WAR or in all Wars in an EAR.The JSP pages are compiled into Java servlet classes and saved in a WAR file. Thisoperation enables the JSP pages to be served faster the first time they are accessed.Syntaxiastool command-line utilities (continued)To...List the partitions on a server and management port. For more information,see “listpartitions” on page 10-15.List the servers on the specified management port. For more information,see “listservers” on page 10-16.List the services on a server and management port. For more information,see “listservices” on page 10-17.Merge a set of JAR files into a single JAR file. For more information, see“merge” on page 10-18.Migrate a JAR or xml file from J2EE 1.2 to J2EE 1.3. For more information,see “migrate” on page 10-19.Apply one or more patches to a JAR file. For more information, see “patch”on page 10-19.Ping a server, service, or Partition for its current state. For moreinformation, see “ping” on page 10-20.Remove stubs from a JAR file. For more information, see “removestubs” onpage 10-22.Restart a server, service, or Partition on a management port. For moreinformation, see “restart” on page 10-22.Set the main class of a Client Jar or a Client Jar in an EAR. For moreinformation, see “setmain” on page 10-24.Start a service or Partition on a management port. For more information, see“start” on page 10-24.Stop a server, service, or Partition on a management port. For moreinformation, see “stop” on page 10-26.Uncompress a JAR file. For more information, see “uncompress” onpage 10-27.Remove a J2EE module from a Partition on a Borland Enterprise Server. Formore information, see “undeploy” on page 10-28.-usageDisplay the usage of command-line options. For more information, see“usage” on page 10-29.-verify Verify a J2EE module. For more information, see “verify” on page 10-30.-compilejsp-src -target [-package ] [-loglevel ] [-classpath ]Default OutputBy default, compilejsp reports if the operation was successful or not.10-2 User’ s Guide

Using the iastool command-line toolsOptionsThe following table describes the options available when using the compilejsp tool.Option-src war or ear-target target file-package package root-loglevel 0-4-classpath classpathDescriptionSpecifies the WAR or EAR file you want to compile. The full or relativepath to the file must be specified. There is no default.Specifies the name of the file to be generated. The file name you specifycannot already exist. The full or relative path to the file must bespecified. There is no default.Specifies the base package name for the precompiled JSP servlet classes.The default is com.bes.compiledjsp.Specifies the amount of output diagnostic messages to be generated. Avalue greater than 2 willalso leave the temporary servlet Java files for further inspection. Thedefault is 2.Specifies any additional libraries that may be required for compiling theJSP pages. There is no default.ExampleTo precompile the JSP pages contained in a WAR file called proj1.war located in thecurrent directory into a WAR file called proj1compiled.war in the same location:iastool -compilejsp -src proj1.war -target proj1compiled.warTo precompile the JSP pages contained in an EAR file called proj1.ear located in thedirectory c:\myprojects\ into an EAR file called proj1compiled.ear in the same locationand generate the maximum amount of diagnostic messages:iastool -compilejsp-srcc:\myprojects\proj1.ear -target c:\myprojects\proj1compiled.ear -loglevel 4compressUse this tool to compress a JAR file.Syntax-compress -src -target Default OutputBy default, compress reports if the operation was successful or not.iastool command-line utility 10-3

Using the iastool command-line toolsOptionsThe following table describes the options available when using the compress tool.Option-src srcjar-target targetjarDescriptionSpecifies the JAR file that you want to compress. The full or relativepath to the file must be specified. There is no default.Specifies the name of the compressed JAR file to be generated. Thefull or relative path to the file must be specified. There is no default.ExampleTo compress a JAR file called proj1.jar located in the current directory into a filecalled proj1compress.jar in the same location:iastool -compress -src proj1.jar -target proj1compress.jarTo compress a JAR file called proj1.jar located in the directory c:\myprojects\ into afile called proj1compress.jar in the same location:iastool -compress -src c:\myprojects\proj1.jar -target c:\myprojects\proj1compress.jardeployUse this tool to deploy a J2EE module to a specified Partition on a specified server orto deploy a J2EE module to a specified cluster.Syntaxor-deploy -jars >-partition [-force_restart] [-cp ] [-args ] [-noverify][-nostubs] [-mgmtport ] [-realm ] [-user ] [-pwd ]-deploy -jars -cluster [-force_restart] [-cp ][-args ] [-noverify] [-nostubs] [-mgmtport ] [-realm ] [-user][-pwd ]Default OutputBy default, deploy reports if the operation was successful.10-4 User’ s Guide

Using the iastool command-line toolsOptionsThe following table describes the options available when using the deploy tool.Option-jars jar1,jar2...-server servername-host host:listener_portPartition partitionnamecluster clustername-force_restart-cp classpath-args args-noverify-nostubs-mgmtport nnnnn-realm realm-user username-pwd passwordDescriptionSpecifies the name(s) of the JAR file(s) to be deployed. To specifymore than one JAR file, enter a comma (,) between each file name.The full or relative path to the file(s) must be specified. There is nodefault.Specifies the name of the Borland Enterprise Server in which todeploy the JAR files. A server must be specified.Specifies the host name and the listener port of the machine onwhich the Borland Enterprise Server you are interested in isrunning. This option enables the iastool utility to locate a serveron a different subnet than the machine on which iastool isrunning.To specify or change the Borland Enterprise Server listener port,include the following line in the management_vbroker.properties filelocated in the

Using the iastool command-line toolsThe following table describes the options that are available for java2iiop.Table 10.2java2iiop Argumentjava2iiop argument list-D, -define foo[=bar]-I, -include dir-P, -no_line_directives-H, -list_includes-C, -retain_comments-U, -undefine foo-[no_]idl_strictDescriptionDefine a preprocessor macro, optionally with valueSpecify additional directory for #include searchingDo not emit #line directives from preprocessor (default isoff)Display #included file names as they are encountered(default is off)Retain comments in preprocessed output (default is off)Undefine a preprocessor macroStrict OMG-standard interpretation of IDL source(default is off)-[no_]builtin (TypeCode|Principal) Create built-in type ”::TypeCode”or ”::Principal” (defaultis default is on)-[no_]warn_unrecognized_pragmas Warn if a #pragma is not recognized (default is on)-[no_]back_compat_mapping Use mapping that is compatible with Visibroker 3.x(default is off)-[no_]preprocessPreprocess the input file before parsing (default is on)-[no_]preprocess_onlyStop parsing the input file after preprocessing (default isoff)-[no_]warn_allTurn all warnings on/off simultaneously (default is off)-exported pkgSpecify an exported package-[no_]export_allExport all packages (default is off)-import IDL file nameLoad extra IDL definitions-imported pkg IDL file name Specify an imported package-[no_]boaBOA-compatible code generation (default is off)-[no_]commentsPlace comments in generated code (default is on)-gen_included_filesGenerate code for #included files (default is off)-list_filesList files written during code generation (default is off)-[no_]obj_wrapperGenerate support for object wrappers (default is off)-root_dir pathDirectory in which generated files should reside-[no_]servantGenerate servant (server-side) code (default is on)-[no_]tieGenerate tie classes (default is on)-[no_]warn_missing_defineWarn if any forward declared names were never defined(default is on)-[no_]bindGenerate bind() code (default is on)-[no_]compileCompile any Java file written automatically (default isoff)-dynamic_marshalMarshaling uses DSI/DII (default is off)-idl2package IDL name pkgOverride default package for a given IDL container type-[no_]invoke_handlerGenerate invocation handler class for EJB (default is off)-[no_]narrow_complianceGenerated code is compliant (versus 3.x compatible)(default is on)10-6 User’ s Guide

Table 10.2java2iiop Argument-[no_]Object_methods-package pkg-stream_marshal-[no_]copy_local_values-strict-version-map_keyword kwd replacement-compiler full name-compilerflags "\-flag,arg[,.]"-[no_]examples-h, -help, -usage, -?-versionclass1 [class2] ...Using the iastool command-line toolsExecuting from a script fileFor information about how to protect login information when running this tool froma script file, see “Executing iastool command-line tools from a script file” onpage 10-31dumpstackUse this tool to obtain diagnostic information about the threads running in aPartition. This tool causes the Partition to generate a stack trace of all threads and theoutput is stored in the Partition's event log file. The stack trace may be useful fordiagnosing problems with the Partition. The log file is located in the directory:install_dir\var\servers\servername\adm\logs\partitions\partitionnameSyntaxjava2iiop argument list (continued)DescriptionGenerate all methods on Object (default is on)Specify root package for generated codeMarshaling uses streams (default is on)Copy values when making collocated calls on CORBAmethods (default is off)Strict OMG-standard code generation (default is off)Display software version numbersSpecify keyword to avoid and its replacementSpecify full name of Java compilerSpecify Java compiler flags (first "-" is escaped, commaseparated)Generate sample implementations (default is off)Print this usage informationDisplay software version numbersOne or more Java classes to process-dumpstack

Using the iastool command-line toolsOptionsThe following table describes the options available when using the dumpstack tool.Option-server servername | -hosthostname:listener_port-partition partitionname-mgmtport nnnnn-realm realm-user username-pwd passwordDescriptionSpecifies the name of the Borland Enterprise Server or the hostname and the listener port of the machine on which the BorlandEnterprise Server you are interested in is running. You mustspecify either a server or a host name and listener port.Specifying a listener port enables the iastool utility to locate aserver on a different subnet than the machine on which iastoolis running.Specifies the name of the Partition that want to diagnose. Thename of a valid Partition must be specified.Specifies the management port number used by the specifiedBorland Enterprise Server. The default is 42424.Specifies the realm used to authenticate a user when the userand password options are specified.Specifies the user to authenticate against the specified serverrealm.Specifies the user's password to authenticate against thespecified server realm.ExamplesThe following example shows how to perform a thread dump of the Partitionstandard on the server BES1:iastool -dumpstack -server BES1 -partition standardThe following example shows how to perform a thread dump of the Partitionstandard on a server running on a computer host on a specific listerner port. Note thatthe -host option can be used regardless of whether iastool is executed on the same ora different host machine on which the server is running.iastool -dumpstack -host mymachine:1234 -partition standardgenclientUse this tool to generate a library containing client stubs files, EJB interfaces, anddependent class files for one or more EJB JAR files and to package them into one ormore client JAR files. The client JAR is not an EJB, but is an EJB client.If genclient fails for one of the EJB JARs in the argument list, an error is displayed andthe genclient tool will continue to attempt to generate a client JAR on the remainderof the specified list.The genclient tool will exit 0, for 100% success, or 1, for any failure.Syntax-genclient -jars -target [-cp ] [-args]10-8 User’ s Guide

Using the iastool command-line toolsDefault OutputThe default output returns nothing to standard output (stdout).OptionsThe following table describes the options available when using the genclient tool.Option-jars jar1,jar2...-target client_jar-cp classpath-args java2iiop_argsDescriptionSpecifies the JAR file(s) for which you want to generate one or moreclient JAR file(s). To specify more than one JAR file, enter a comma(,) between each file name. The full or relative path to the JAR file(s)must be specified. There is no default.Specifies the client-JAR file(s) to be generated on the localhost. Thefull or relative path to the JAR file(s) must be specified. There is nodefault.Specifies the classpath containing the class dependencies of the JARfile for which you want to generate a client JAR file(s). The defaultis none. This parameter is optional.Specifies any arguments that are needed by the file. For details, seeTable 10.2, “java2iiop argument list,” on page 10-6 and see theBorland Enterprise Server Developer's Guide for information aboutjava2iiop. This parameter is optional.ExampleThe following example shows how to generate a manually deployable module clientJAR file from each of the EJB JAR files: proj1.jar, proj2.jar, and proj3.jar into the EJBJAR myproj.jar.iastool -genclient -jars proj1.jar proj2.jar proj3.jar -target myproj.jargendeployableUse this tool to create a manually deployable server-side module. Server-sidedeployable JAR files are archives (EAR, WAR, or JAR beans only) that have beencompiled to resolve all external code references by using stubs and are, therefore,ready for deployment.For example, first use gendeployable to create the server-side deployable JAR file on alocal machine, then use the deploy tool to copy and load it on the server. The server isadvised of the presence of the new JAR file and loads it automatically. Using thecommand-line tools lets you script a creation and deployment to several servers quitesimply. You can also manually copy the server-side deployable JAR file to the correctlocation on each server, but this requires restarting each server to cause it to berecognized and loaded.Syntax-gendeployable -src -target [-cp ] [-args]iastool command-line utility 10-9

Using the iastool command-line toolsDefault OutputThe default output returns nothing to standard output (stdout).OptionsThe following table describes the options available when using the gendeployable tool.Option-src input_jar-target output_jar-cp classpath-args java2iiop_argsDescriptionSpecifies the JAR file that you want to use to generate a newdeployable JAR file. The full or relative path to the JAR file must bespecified. There is no default.Specifies the deployable JAR file(s) to be generated on the localhost.The full or relative path to the JAR file(s) must be specified. There isno default.Specifies the classpath containing the class dependencies of the JARfile for which you want to generate a client JAR file(s). The defaultis none. This parameter is optional.Specifies any arguments that are needed by the file. For details, seeTable 10.2, “java2iiop argument list,” on page 10-6 and see theBorland Enterprise Server Developer's Guide for information aboutjava2iiop. This parameter is optional.ExampleThe following example shows how to generate a server-side deployable module JARfile for proj1.jar into the file server-side.jar.iastool -gendeployable -src proj1.jar -target serverside.jargenstubsUse this tool to create a stubs library file containing client or server stubs.Syntax-genstubs -src -target [-client] [-cp ] [-args]Default OutputThe default output returns nothing to standard output (stdout).10-10 User’ s Guide

Using the iastool command-line toolsOptionsThe following table describes the options available when using the genstubs tool.Option-src input_jar-target output_jar-client-cp classpath-args java2iiop_argsDescriptionSpecifies 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 nodefault.Specifies the name of the JAR file that will be generated on thelocalhost. The full or relative path to the JAR file(s) must be specified.There is no default.Specifies that you want to generate client sides stubs. If this option isnot specified, the genstubs tool will generate server side stubs.Specifies the classpath containing the class dependencies of the JAR filefor which you want to generate a client JAR file(s). The default is none.This parameter is optional.Specifies any arguments that are needed by the file. For details, seeTable 10.2, “java2iiop argument list,” on page 10-6 and see the BorlandEnterprise Server Developer's Guide for information about java2iiop.This parameter is optional.ExamplesThe following example shows how to generate a server-side stubs of the EJB JARproj1.jar into the EJB JAR server-side.jar.iastool -genstubs -src proj1.jar -target serverside.jarThe following example shows how to generate a client-side stub file for the EJB JARmyproj.jar into the EJB JAR client-side.jar.iastool -genstubs -src c:\dev\proj1.jar -target -client c:\builds\client-side.jariaschangeowner (UNIX only)Some files and directories, such as log files, properties, and realms are not createdwhen the Borland Enterprise Server is installed. Instead, they are created by theserver at runtime, the first time the server is started. Permissions on these files anddirectories are granted based on the user running the server at this initial time. Forexample, if you run the server for the first time as usernameA, some files or directorieswill be owned by usernameA. Any subsequent running of the server by any other user(including root) will result in error due to permission problems. File ownership mustbe changed in order to allow any other users to write to these files.Changing ownership of a server instanceTo change ownership of a server instance, use the iaschangeowner script (UNIX only)in the /bin directory of the installed Borland Enterprise Server. The script changes theownership of files such as logs and properties to allow writing by another owner.The following directories (and their contents) are affected by the iaschangeowner script:• /var/defaultsiastool command-line utility 10-11

Using the iastool command-line tools• /var/bms• /var/servers/• /SonicMQNoteUsageThis version of Borland Enterprise Server includes two new iaschangeowner options,the and . When a Borland Enterprise Server installation hasmultiple server instances defined, the ownership of each instance can be set todifferent or the identical users.Usage: iaschangeowner -r [-s | -d]-o -g [-a]When a Borland Enterprise Server installation has multiple server instances defined,the ownership of each instance can be set to different or identical users.• -r : The root directory of the Borland Enterprise Server installation.• -d Defaults (templates): Change the ownership of future servers. -d and -s cannotbe specified at the same time.• -s : The name of the server instance to change ownership of. This isnot required if the server only contains one server instance. -d and -s cannot bespecified at the same time.• -o : The user id of the new owner, e.g.; nobody, root, etc.• -g : The group id of the new group.• -a: If owner is root, set Apache to run as root. Otherwise, set Apache to run as theuser who starts it (or the Borland Enterprise Server).RulesThe following rules apply:• If neither -s or -d are specified, and only one server was created, ownership of thatserver will be changed. An error will be generated if more than one server exists.• If -s is specified, only that server's files will be changed. -d cannot bespecified at the same time.• If -d is specified, all the files in /var/default will be updated and therefore any newserver will be owned by the new user. -s cannot be specified at this time.• bms and SonicMQ directories will always be changed to the new owner.ExampleThe following is a short example using the iaschangeowner script to change the username and group for any servers started from the /usr/BES installation:% iaschangeowner -r /usr/BES -d -o jsmith -g admin10-12 User’ s Guide

Using the iastool command-line toolsFailure to change permissions prior to changing server owners will result in errorssimilar to the following:bin/ias: server_root/sk.txt: cannot createinfoUse this tool to display the system configuration information in use when startingBorland Enterprise Server.Syntaxiastool -infoDefault OutputThe default output is the current configuration information used by the BorlandEnterprise server currently running on the local machine. For example, the first fewlines of output look like the following partial listing:application.home: C:\Program Files\BESawt.toolkit: sun.awt.windows.WToolkitfile.encoding: Cp1252file.encoding.pkg: sun.iofile.separator : \java.awt.fonts :java.awt.graphicsenv: sun.awt.Win32GraphicsEnvironmentjava.awt.printerjob: sun.awt.windows.WPrinterJobjava.class.path: C:\Program Files\BES\jdk\lib\tools.jar....OptionsThe info tool provides no options.ExampleThe following example shows how to display configuration information.killiastool -infoUse this tool to stop a server, service, or Partition on a specified management port.Syntax-kill > [-mgmtport ][-service | -partition ] [-realm ] [-user ] [-pwd ]iastool command-line utility 10-13

Using the iastool command-line toolsDefault OutputBy default, the kill tool lists the managed object that has been killed.OptionsThe following table describes the options available when using the kill tool.Option-server servername-host host:listener_port-mgmtport nnnnn-service servicename-partition partitionname-realm realm-user username-pwd passwordDescriptionSpecifies the name of the Borland Enterprise Server that you wantto stop.Specifies the host name and the listener port of the machine onwhich the Borland Enterprise Server you are interested in isrunning. The option is enables the iastool utility to locate a serveron adifferent subnet than the machine on which iastool is running.To specify or change the Borland Enterprise Server listener port,include the following line in the management_vbroker.properties filelocated in the

Using the iastool command-line toolslistpartitionsUse this tool to list the partitions running on a specified server and, optionally, on aspecified management port.Syntax-listpartitions

Using the iastool command-line toolsThe following example lists the partitions running on the server tiger using themanagement port 24410:iastool -listpartitions -server tiger -mgmtport 24100Executing from a script fileFor information about how to protect login information when running this tool froma script file, see “Executing iastool command-line tools from a script file” onpage 10-31.listserversUse this tool to list Borland Enterprise Server instances running on a particularmanagement port located on the same local area network.Syntax-listservers [-mgmtport ] [-bare] [-realm ][-user ] [-pwd ]NoteDefault OutputBy default, the listservers tool displays the servers running in the defaultmanagement port or on a specified management port.If a particular server that is queried is down, it is not listed.OptionsThe following table describes the options available when using the listservers tool.Option-mgmtport nnnnn-bare-realm realm-user username-pwd passwordDescriptionSpecifies a management port number of the running servers you want to list.The default is 42424.Suppresses output information, other than the names of the running servers.Specifies the realm used to authenticate a user when the user and passwordoptions are specified.Specifies the user to authenticate against the specified server realm.Specifies the user's password to authenticate against the specified serverrealm.ExamplesThe following example lists the servers running in the default management port:iastool -listserversThe following example lists the servers running in the management port 24410:iastool -listservers -mgmtport 2410010-16 User’ s Guide

Using the iastool command-line toolsExecuting from a script fileFor information about how to protect login information when running this tool froma script file, see “Executing iastool command-line tools from a script file” onpage 10-31.listservicesUse this tool to list one or more Borland Enterprise Server services managed by aserver instance.Syntax-listservices [-mgmtport ][-bare] [-realm ] [-user ] [-pwd ]Default OutputBy default, listservices displays a list of all services registered for the specified serveron a particular management port. For example:List of Services on the server eastdiv in domain 42424:apache1_3sonicmqosagentOptionsThe following table describes the options available when using the listservices tool.Option-server servername-host host:listener_port-mgmtport nnnnn-bare-realm realmDescriptionSpecifies the name of the Borland Enterprise Server for which youwant to list the running services.Specifies the host name and the listener port of the machine onwhich the Borland Enterprise Server you are interested in isrunning. The option is enables the iastool utility to locate a serveron a different subnet than the machine on which iastool is running.To specify or change the Borland Enterprise Server listener port,include the following line in the management_vbroker.properties filelocated in the

Using the iastool command-line toolsOption-user username-pwd passwordDescriptionSpecifies the user to authenticate against the specified server realm.Specifies the user's password to authenticate against the specifiedserver realm.ExampleThe following example lists all services running on the salsa server:iastool -listservices -server salsaExecuting from a script fileFor information about how to protect login information when running this tool froma script file, see “Executing iastool command-line tools from a script file” onpage 10-31.mergeUse this tool to produce a single, new Java Archive file (EJB-JAR) containing thecontents of a specified list of EJB-JARs. Multiple EJB 1.1 and EJB 2.0 deploymentdescriptors (if any) will be consolidated into a single deployment descriptor. Ifmerging fails for one of the EJB-JARs in the argument list, an error is displayed, andthe merge command will exit indicating failure.Syntax-merge -jars -target -type Default OutputThe default output returns nothing to standard output (stdout).OptionsThe following table describes the options available when using the merge tool.Option-jars jar1,jar2,..-target JAR file name-type ejb1.1|ejb2.0|ear1.2|ear1.3|libDescriptionSpecifies the JAR file(s) to merge. The full or relative path to theJAR file(s) must be specified. There is no default.Specifies the new JAR file to be created containing the mergedcontents of the specified list of JAR files. The full or relative pathto the new JAR file must be specified. There is no default.Specifies the type of the new archive file using one of thefollowing supported formats:•ejb1.1 - Version 1.1 Enterprise Java Bean•ejb2.0 - Version 2.0 Enterprise Java Bean•ear1.2 - Version 1.2 Enterprise Application Resource•ear1.3 - Version 1.3 Enterprise Application Resource•lib - Library file10-18 User’ s Guide

Using the iastool command-line toolsExampleThe following example merges the EJB-JAR files proj1.jar, proj2.jar, and proj3.jarinto a new version 2.0 EJB-JAR file named combined.jar:iastool -merge -jars proj1.jar, proj2.jar, proj2.jar -target combined.jar -type ejb2.0migrateNoteUse this tool to convert a JAR or .xml file from J2EE version 1.2 to J2EE version 1.3.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 yourdeployment.If the conversion fails, an error is displayed.Syntax-migrate -src srcjar -target targetjarDefault OutputThe default returns nothing to standard output (stdout).OptionsThe following table describes the options available when using the migrate tool.Option-src jar file name-target jar file nameDescriptionSpecifies the J2EE version 1.2 file to convert. The full or relative path tothe JAR file must be specified. There is no default.Specifies the name of the J2EE version 1.2 file to be created. The full orrelative path to the JAR file must be specified. There is no default.ExampleThe following example migrates the file myj1_2.jar from J2EE version 1.2 to J2EEversion 1.3 into new file called myj1_3.jar:iastool -migrate -src -target patchUse this tool to apply one or more patches to a JAR file and produce a new JAR filewith the applied patches.Syntax-patch -src -patches -target iastool command-line utility 10-19

Using the iastool command-line toolsDefault OutputThe default output displays the patches that were applied.OptionsThe following table describes the options available when using the patch tool.Option-src jar file name-patches patch1_jar,...-target jar file nameDescriptionSpecifies the JAR file to which you want to apply one or morepatches. The full or relative path to the JAR file must be specified.There is no default.Specifies one or more JAR files that contain the patches you want toapply. To specify more than one file, enter a comma (,) between eachfile name. The full or relative path to the file(s) must be specified.There is no default.Specifies the name of the new JAR file to be created. The full orrelative path to the JAR file must be specified. There is no default.ExampleThe following example applies the patches contained in the files mypatch1.jar andmypatch2.jar to the file myold.jar which are all located in the current directory andcreates a new file called mynew.jar in the same location:iastool -patch -src myold.jar -patches mypatch1.jar,mypatch2.jar -target mynew.jarpingUse this tool to verify connections to the Borland Enterprise Server, a service runningon a specified server, or a Partition running on a specified server instance or to verifyconnections to a server, service, or Partition on a specified management port. Theping command will return nothing for a server that is not running.Syntax-ping [-mgmtport ][-service | -partition ] [-realm ] [-user ] [-pwd ]Default OutputThe default output shows the name and status of the server (and optionally theservice or Partition) if the process is pinged and running. For example:Pinging Server xyz_corp1: RunningThe ping tool returns one of the following states:• Running• Starting• Stopping10-20 User’ s Guide

Using the iastool command-line tools• Not Running• Restarting• Cannot Load• Cannot Start• Terminated• UnknownOptionsThe following table describes the options available when using the ping tool.Option-server server_name-host host:listener_port-mgmtport nnnnn-service servicename-partition partitionname-realm realm-user username-pwd passwordDescriptionSpecifies the server to ping or whose services to ping. There is nodefault.Specifies the host name and the listener port of the machine onwhich the Borland Enterprise Server you are interested in isrunning. The option is enables the iastool utility to locate a serveron adifferent subnet than the machine on which iastool is running.To specify or change the Borland Enterprise Serverlistener port, include the following line in themanagement_vbroker.properties file located in the

Using the iastool command-line toolsiastool -ping -server waba -mgmtport 24410 -service TomcatExecuting from a script fileFor information about how to protect login information when running this tool froma script file, see “Executing iastool command-line tools from a script file” onpage 10-31.removestubsUse this tool to remove all stub files from a JAR file.Syntax-removestubs -jars [-targetdir ]Default OutputThe default output returns nothing to standard output (stdout).OptionsThe following table describes the options available when using the removestubs tool.Option-jars jar1,jar2...-targetdir dirDescriptionSpecifies the JAR file(s) from which you want to remove one or more stubfiles. To specify more than one JAR file, enter a comma(,) after each JARfile. The full or relative path to the JAR file(s) must be specified. There isno default.Specifies the directory in which the stub files that were removed will bestored. A full or relative path must be specified, if this option is specified.There is no default. If no target directory is specified, the stub files will beremoved, but not saved.ExampleThe following example shows how to remove stub files located from the EJB JAR filesproj1.jar, proj2.jar, and proj3.jar located in the current directory and copy them to c:\examples\proto:iastool -removestubs -jars proj1.jar, proj2.jar, proj3.jar -targetdir c:\examples\protorestartUse this tool to restart the Borland Enterprise Server, or to restart a service orPartition running on a specified server, and optionally on a specified managementport. The server must already be initialized in order for the restart tool to initialize aservice or Partition on the server.10-22 User’ s Guide

Using the iastool command-line toolsSyntax-restart [-mgmtport ] [-service | -partition ][-realm ] [-user ] [-pwd ]Default OutputThe default output displays the managed object that has been restarted.If the restart tool fails (for example, when a service cannot be shutdown or restarted),an error is displayed with a status code which is returned to standard error output(stderr) as well as being recorded in the server's error log.OptionsThe following table describes the options available when using the restart tool.Option-server servername-host host:listener_port-mgmtport nnnnn-service servicename-partition partitionname-realm realm-user username-pwd passwordDescriptionSpecifies the name of the Borland Enterprise Server that you wantto restart.Specifies the host name and the listener port of the machine onwhich the Borland Enterprise Server you are interested in isrunning. The option is enables the iastool utility to locate a serveron adifferent subnet than the machine on which iastool is running.To specify or change the Borland Enterprise Serverlistener port, include the following line in themanagement_vbroker.properties file located in the

Using the iastool command-line toolsiastool -restart -server tiger -mgmtport 24410 -service TomcatExecuting from a script fileFor information about how to protect login information when running this tool froma script file, see “Executing iastool command-line tools from a script file” onpage 10-31.setmainUse this tool to set the main class of a standalone Client JAR or a Client JAR in anEAR file. Once the main class is set, the java -jar jarfile command willautomatically invoke the main class that has been set for the JAR file.Syntaxsetmain -jar [-uri ] -class Default OutputThe default output displays the main class that has been set for the specified JAR file.OptionsThe following table describes the options available when using the setmain tool.Option-jar jar or ear-uri uri_path-class main_class_nameDescriptionSpecifies the name of the JAR or EAR file on which you want to set themain class.If you are setting the main class for an EAR file, you must use the -urioption to identify the URI (Uniform Resource Identifier) path of theclient JAR in the EAR.Specifies the class name that will be set as the main class in the specifiedClient JAR. The class must exist in the client JAR file and contain amain() method.ExamplesThe following example sets a main class for a standalone Client JAR:iastool -setmain -jar myclient.jar -class com.bes.myjclassThe following example sets a main class for a Client JAR contained in an EAR file:iastool -setmain -jar myapp.ear -uri base/myapps/myclient.jar -class com.bes.myjclassstartUse this tool to start a service or Partition on a specified Borland Enterprise Server oroptionally on a specified management port. The server instance must already beinitialized in order for the start tool to initialize services on that server. The start tool10-24 User’ s Guide

Using the iastool command-line toolswill not initialize a server instance; to initialize a server instance, use the iascommand.Syntax-start [-mgmtport ] -service | -partition [-realm ] [-user ] [-pwd ]Default OutputThe default output displays the managed object that has been started.OptionsThe following table describes the options available when using the start tool.Option-server servername-host host:listener_port-mgmtport nnnnn-service servicename-partition partitionname-realm realm-user username-pwd passwordDescriptionSpecifies the name of the Borland Enterprise Server that youwant to start.Specifies the host name and the listener port of the machine onwhich the Borland Enterprise Server you are interested in isrunning. The option is enables the iastool utility to locate aserver on adifferent subnet than the machine on which iastool is running.To specify or change the Borland Enterprise Server listenerport, include the following line in themanagement_vbroker.properties file located in the

Using the iastool command-line toolsExecuting from a script fileFor information about how to protect login information when running this tool froma script file, see “Executing iastool command-line tools from a script file” onpage 10-31.stopUse this tool to shut down a server, service, or a Partition on a specified BorlandEnterprise Server or, optionally, on a specified management port. The server instancemust already be initialized in order for the stop tool to shut down services on thatserver.Syntax-stop [-mgmtport ][-service | -partition ] [-realm ] [-user ] [-pwd ]Default OutputThe default output displays the process or processes that have been shut down.If the stop tool fails (e.g. when a service cannot be shutdown), an error is displayedwith a status code, which is returned to standard error output (stderr), as well asbeing recorded in the server's error log.OptionsThe following table describes the options available when using the stop tool.Option-server servername-host host:listener_port-mgmtport nnnnn-service servicenameDescriptionSpecifies the name of the Borland Enterprise Server that you want toshut down.Specifies the host name and the listener port of the machine onwhich the Borland Enterprise Server you are interested in is running.The option is enables the iastool utility to locate a server on adifferent subnet than the machine on which iastool is running.To specify or change the Borland Enterprise Serverlistener port, include the following line in themanagement_vbroker.properties file located in the

Using the iastool command-line toolsOption-partition partitionname-realm realm-user username-pwd passwordDescriptionSpecifies the name of the Partition that you want to shut down. Thisoption and the -service option cannot be used at the same time. Ifnot specified, all partitions on the specified server are stopped.Specifies the realm used to authenticate a user when the user andpassword options are specified.Specifies the user to authenticate against the specified server realm.Specifies the user's password to authenticate against the specifiedserver realm.ExampleThe following example stops the Tomcat service running on the server tiger in themanagement port 24410:iastool -stop -server tiger -mgmtport 24410 -service TomcatExecuting from a script fileFor information about how to protect login information when running this tool froma script file, see “Executing iastool command-line tools from a script file” onpage 10-31.uncompressUse this tool to uncompress a JAR file.Syntax-uncompress -src -target Default OutputBy default, uncompress reports if the operation was successful or not.OptionsThe following table describes the options available when using the uncompress tool.Option-src srcjar-target targetjarDescriptionSpecifies the JAR file that you want to uncompress. The full or relative pathto the file must be specified. There is no default.Specifies the name of the uncompressed JAR file to be generated. The full orrelative path to the file must be specified. There is no default.ExamplesThe following example converts the compressed JAR file called small.jar located inthe current directory into an uncompressed file called big.jar in the same location:iastool -uncompress -src small.jar -target big.jariastool command-line utility 10-27

Using the iastool command-line toolsThe following example uncompresses a JAR file named small.jar located in thedirectory c:\myprojects\ into a file named big.jar in the same location:iastool -uncompress -src c:\myprojects\small.jar -target c:\myprojects\big.jarundeployUse this tool to undeploy a J2EE module from a specified Partition on a specifiedserver or to undeploy a J2EE module from a specified cluster.Syntaxor-undeploy -jar -partition [-mgmtport ] [-realm ] [-user ] [-pwd]-undeploy -jar -cluster [-mgmtport ][-realm ][-user ] [-pwd ]Default OutputBy default, the undeploy tool reports if the operation was successful or not.OptionsThe following table describes the options available when using the undeploy tool.Option-jar jar file name-server servername-host host:listener_port-partition partitionnameCluster clustername-mgmtport nnnnnDescriptionSpecifies the name of the JAR file to be undeployed. The full orrelative path to the file must be specified. There is no default.Specifies the name of the Borland Enterprise Server from which toundeploy the JAR file.Specifies the host name and the listener port of the machine onwhich the Borland Enterprise Server you are interested in isrunning. The option is enables the iastool utility to locate a serveron adifferent subnet than the machine on which iastool is running.To specify or change the Borland Enterprise Server listener port,include the following line in the management_vbroker.properties filelocated in the

Using the iastool command-line toolsOption-realm realm-user username-pwd passwordDescriptionSpecifies the realm used to authenticate a user when the user andpassword options are specified.Specifies the user to authenticate against the specified server realm.Specifies the user's password to authenticate against the specifiedserver realm.Executing from a script fileFor information about how to protect login information when running this tool froma script file, see “Executing iastool command-line tools from a script file” onpage 10-31usageUse this tool to display a list and a brief description of each of the command-linetools provided by the iastool utility, or to display a more detailed description of oneor more specified tools.SyntaxNote-usage-usage tool-usage tool1 tool2 tool3Arguments to the usage command do not require a leading hyphen.Default OutputBy default, the usage tool displays a list and a brief description of each command-linetools.OptionsThe following table describes the options available when using the usage tool.OptionusageUsagetool1 tool2 tool3...DescriptionDisplays a list and a brief description of each the iastool commandlinetools.Displays a more detailed description of one or more iastoolcommand-line tools.ExamplesThe following example displays a list and a brief description of each the commandlinetools:iastool -usageThe following example displays detailed information on the compress tool:iastool -usage compressiastool command-line utility 10-29

Using the iastool command-line toolsThe following example displays detailed information on the -start, -stop, and -restart tools:iastool -usage start stop restartverifyUse this tool to check an archive file for correctness and consistency, and to check ifall the elements required for deploying your application are in place.The Borland Enterprise Server verification process supports the following roles thatcorrespond to a phase in the application's life cycle and the appropriate level ofverification (similar to the J2EE role definitions):• Developer: This is the lowest verification level. All xml is checked for syntax aswell as standard and proprietary keywords relevant to the current archive type.Consistency across the archive is checked, but no external resources are verified atthis level.• Assembler: Once the archives are individually verified and are correct, otherresources built into an application will start to be verified. For example, this levelwill verify the existence and correctness of URIs (Uniform Resource Identifiers),but not EJB or JNDI links.• Deployer: (the default) All checks are turned on. EJB and JNDI links are checkedat this level as well as the operational environment in which the application is tobe deployed.Supported archive types are EAR, EJB, WAR, JNDI, and Client Jars The typicalarchive verification process includes the following checks:• A pass over the XML code, checking for correct XML syntax• Verification of the semantics of the standard and proprietary xml descriptors, andthe compliance with their required descriptors for each supported archive typeVerification always occurs in a hierarchical fashion, starting with the top module,then recursively working through its submodules, and finally checking for interarchivelinks.Syntax-verify -src srcjar -role [-nowarn] [-strict] [-classpath]Default OutputBy default, verify reports nothing (for example, if no errors are found in the specifiedmodule).10-30 User’ s Guide

Executing iastool command-line tools from a script fileOptionsThe following table describes the options available when using the verify tool.Option-src srcjar-role DEVELOPER|ASSEMBLER|DEPLOYER-nowarn-strict-classpath classpathDescriptionSpecifies the JAR file that you want to verify. The full orrelative path to the file must be specified. There is no default.Specifies the level of error checking to perform:•DEVELOPER•ASSEMBLER•DEPLOYER (default)For details, see the role descriptions above.Specifies to only report errors that preclude deployment andnot report warnings.Specifies to report the most minute inconsistencies, many ofwhich do not affect the overall integrity of the application.Specifies the search path for application classes andresources. To enter more than one directory, zip, or JAR fileentry, separate each entry with a semicolon (;).ExampleThe following example performs a developer level verification of the JAR file soapclient.jarlocated in the c:\examples\soap directory:-verify -src c:\examples\soap\soap-client.jar -role DEVELOPERExecuting iastool command-line tools from a script fileSeveral iastool utility tools require that you supply login information (realm,username, and password). You may, however, want to run iastool commands from ascript file, but doing so would expose the realm, username, password information toanyone who has access to the script file. There are two methods you can use toprotect this information:• See “Piping a file to the iastool utility” on page 10-31.• See “Passing a file to the iastool utility” on page 10-32.Piping a file to the iastool utilityThe following example shows how to ping a server named east1 by piping the filemylogin.txt (located in the default Borland Enterprise Server installation directory) tothe iastool utility:iastool -ping -server east1 < c:\BES\mylogin.txtiastool command-line utility 10-31

Executing iastool command-line tools from a script fileNotewhere the file mylogin.txt contains three lines that correspond to what you wouldenter for the realm, username, and password:2usernamepasswordThe contents of the file are exactly what you would enter on the command-line: thefirst entry in the file is realm option - not the realm name, but the number you wouldchoose from the list presented to you if you run the ping tool without the realmoption. The second line is the username and the third line is the password. This filecan then be secured in such a way that it is readable by the iastool utility, but not byunauthorized users.Passing a file to the iastool utilityThe following command shows how to ping a server named east1 by passing a file tothe iastool utility using the -file option:iastool -ping -server east1 -file c:\BES\mylogin.txtwhere mylogin.txt has the following format:Default LoginSmart Agent port numberusernamepasswordfalseServerRealmThe -file option: requires that you supply a fully qualified file name (the file nameplus a relative or absolute path). When passing a file to the iastool utility, only thethird, fourth, and sixth lines are used, which are the username, password, and realmname, respectively. The other lines must be present, but the information they containis ignored by the iastool utility. For example:Default Login12448myusernamemypasswordfalseServerRealm10-32 User’ s Guide

11ChapterChapter11Dreamweaver UltraDev Plug-inImportantThis chapter describes how to install, configure, and use the Dreamweaver UltraDevPlug-in for Borland Enterprise Server. The Dreamweaver UltraDev Plug-in allowsyou to turn your web page into a Java Server Page (JSP) by adding JSP tags. Once youhave installed and configured the Dreamweaver UltraDev Plug-in, the supported JSPtags appear on a separate JSP tab in the Objects palette. They also appear under theInsert menu.For documentation updates, go to www.borland.com/techpubs/bes.Installing the Dreamweaver UltraDev Plug-inTo install the Dreamweaver UltraDev Plug-in:1 Verify that you have installed Macromedia Dreamweaver. If you have not yetinstalled Dreamweaver, install it now.2 Make sure Dreamweaver is not running.3 Double click on the executable file, BorlandDWJSP.mxp, in the Install directory.4 When the Macromedia Extension Manager loads, Follow the on-screeninstructions.Dreamweaver UltraDev Plug-in 11-1

Configuring Dreamweaver to use the JSP ExtensionFigure 11.1Macromedia Extension ManagerNoteA popup message will inform you when the Dreamweaver UltraDev Plug-in hasbeen installed.To launch the Borland Enterprise Server Console at any time, select Commands|Launch Borland Enterprise Server Console.Configuring Dreamweaver to use the JSP ExtensionDreamweaver has its own JSP and ASP translators, both of which will recognizesimilar tags created by the JSP extension. In order to prevent these translators fromtranslating the JSP pages created using the JSP extension, you have to disable thembefore using the extension.To configure Dreamweaver's JSP and ASP translators to ignore JSP files created usingthe JSP extension1 Launch the Macromedia Dreamweaver application.2 Select Edit|Preferences.3 In the Preferences dialog box select the category, Translation.11-2 User’ s Guide

Configuring Dreamweaver to use the JSP ExtensionFigure 11.2Preferences dialog box4 From the Translators list select ASP. Under Automatically Translate ASP, check InNo Files.5 From the Translators list select JSP. Under Automatically Translate JSP, check InNo Files.6 Click OK.To configure the JSP Extension:1 Select Commands|Borland JSP Configuration. The Borland JSP ExtensionConfiguration dialog box appears.Figure 11.3Borland JSP Extension Configuration dialog boxNote2 Place a check mark next to Short Form Syntax if you want to use the short formsyntax for JSP tags. For example, the short form for the JSP expression start andend tags and are the tags . This is anoption that can be changed at any time. The change is effective immediately, butonly affects tags inserted after the change.3 Select Disable ASP.4 This step must be done in order to use Dreamweaver UltraDev Plug-ins. Whenworking with ASP, you can return to the Borland JSP Extension Configurationdialog, and select Enable ASP.Whenever you change the Enable ASP or Disable ASP selection, you have to exitand then restart Dreamweaver for the change to be effective.Dreamweaver UltraDev Plug-in 11-3

Inserting JSP tags into your Java Server Page5 Click OK.6 Exit and then restart Dreamweaver for the ASP setting to be effective.Inserting JSP tags into your Java Server PageThe JSP Extension allows you to insert the following tags into your Java Server Page:• See “HTML comments” on page 11-4• See “JSP declarations” on page 11-5• See “JSP expressions” on page 11-6• See “JSP forward actions” on page 11-7• See “JSP getProperty actions” on page 11-8• See “JSP hidden comments” on page 11-9• See “JSP include actions” on page 11-9• See “JSP include directives” on page 11-11• See “JSP page directives” on page 11-11• See “JSP Plug-in actions” on page 11-13• See “JSP scriptlets” on page 11-15• See “JSP getProperty actions” on page 11-8• See “JSP taglib directives” on page 11-16• See “JSP useBean actions” on page 11-17For more information on the syntax of these tags see the ”JavaServer Pages SyntaxCard” at http://www.java.sun.comHTML commentsAn HTML comment is text that is not interpreted by the JSP server. HTML commentsdo appear in the HTML source sent to the client, but they do not appear in thedisplayed page. HTML comments can be used for debugging or documentation. To”comment out” part of your JSP page, you should use a JSP hidden comment.To insert an HTML comment into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu.The Objects palette displays the supported JSP tags.2 Select the HTML Comment icon from the Objects palette. The HTMLComment dialog box appears.11-4 User’ s Guide

JSP declarationsFigure 11.4HTML Comment dialog boxNote3 Enter the Comment text.4 Click OK.The text is inserted into your JSP page between the HTML comment tagsAn HTML comment can also be inserted using the Insert|HTML Comment menuitem.JSP declarationsA JSP declaration declares one or more variables or methods that are used later in theJSP page. These variables and methods do not produce anything that is sent to theclient, and are initialized upon the initial processing of the JSP page. Declarations,scriptlets, and expressions all have access to JSP declarations.To insert a JSP declaration into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the Declaration icon from the Objects palette. The JSP Declaration dialogbox appears.Dreamweaver UltraDev Plug-in 11-5

JSP expressionsFigure 11.5JSP Declaration dialog boxNote3 Enter the Java Declaration.4 Click OK.The variables and methods being declared are inserted into your JSP page betweenthe JSP declaration tags (short form) or andA JSP declaration can also be inserted using the Insert|JSP Declaration menu item.JSP expressionsA JSP expression is a Java language expression that is evaluated by the JSP server andthen converted into a string which replaces the expression in the generated HTMLpage. JSP expressions can be complex. The component parts or expressions areevaluated from left to right. If the expression fails to return a string, an error orexception occurs.To insert a JSP expression into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the Expression icon from the Objects palette. The JSP Expression dialogbox appears.>11-6 User’ s Guide

JSP forward actionsFigure 11.6JSP Expression dialog boxNote3 Enter the Java Expression. Expressions cannot end with a semicolon, unless theyare within a JSP scriptlet.4 Click OK.The Java expression is inserted into your JSP page between the JSP expression tags (short form) or and A JSP expression can also be inserted using the Insert|JSP Expression menu item.JSP forward actionsA JSP forward action terminates the execution of the JSP page, and forward theclient's request information to another server page. The target for a JSP forwardaction can be an HTML file, a JSP file, or a servlet, of the same application. A JSPforward action can forward parameters to the target.To insert a JSP forward action into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. Objectspalette displays the supported JSP tags.2 Select the Forward Action icon from the Objects palette.The JSP Forward Action dialog box appears.Figure 11.7 Forward Action dialog box3 Enter the target Page (a relative URL) to which the request must be forwarded.Dreamweaver UltraDev Plug-in 11-7

JSP getProperty actions4 Enter any Parameters you need to pass to the target page. To add a parameter,click the New button. The Parameters dialog box appears.Figure 11.8Parameters dialog boxNote5 Enter the Name and the Value of the parameter. Click OK.6 The parameter appears in the Parameters field in the JSP Forward Action dialogbox.7 To delete or modify a parameter, select the parameter in the Parameters field andclick the Delete button or the Edit button.8 When you have finished entering the desired parameters, click OK.The forward action is inserted into your JSP page as the JSP forward tags and . If you are passing parameters the JSP paramtag,, appears between the JSP forward tags andA JSP forward action can also be inserted using the Insert|JSP Forward Action menuitem.JSP getProperty actionsA JSP getProperty action reads a property value from a Bean instance and outputsthe value as a string. The definition of the Bean must appear in the JSP page, beforethe JSP getProperty action is used. An exception is raised if an instance cannot befound.To insert a JSP getProperty action into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the getProperty Action icon from the Objects palette. The JSPgetProperty Action dialog box appears.Figure 11.9getProperty Action dialog box3 Enter the Name of the Bean instance containing the property. This Name refers tothe same name used in the useBean action's ID field when the Bean was defined.4 Enter the name of the Property.11-8 User’ s Guide

JSP hidden commentsNote5 Click OK.The getProperty action is inserted into your JSP page embedded in the JSPgetProperty tag A JSP getProperty action can also be inserted using the Insert|JSP getProperty Actionmenu item.JSP hidden commentsA JSP hidden comment is text that is not interpreted by the JSP server. Hiddencomments are not sent to the client. Hidden comments can be used both fordocumentation and to ”comment out” part of your JSP page.To insert a JSP hidden comment into your JSP page1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the Hidden Comment icon from the Objects palette. The JSP HiddenComment dialog box appears.Figure 11.10 Hidden Comment dialog boxNote3 Enter the Comment text.4 Click OK.The text is inserted into your JSP page between the JSP hidden comment tagsA JSP hidden comment can also be inserted using the Insert|JSP Hidden Commentmenu item.JSP include actionsA JSP include action allows either a dynamic or static file to be included in your JSPpage. A dynamic page fulfills a request and the result is included in the translatedJSP page. A static page is included in the translated JSP page. After processing the JSPDreamweaver UltraDev Plug-in 11-9

JSP include actionsinclude action, the JSP server continues processing the rest of the JSP page. A JSPinclude action is useful when you do not know if the included file is static ordynamic. If the included file is dynamic, you can forward parameters to the file.To insert a JSP include action into your JSP page1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the Include Action icon from the Objects palette. The JSP Include Actiondialog box appears.Figure 11.11 JSP Include Action dialog box3 Enter the Page, a relative URL of the include file.4 Set Flush to ”true” if you want buffered HTML output to be ”flushed” to the clientbefore the file is included.5 Enter any Parameters you need to pass to the dynamically included file.6 To add a parameter, click the New button. The Parameters dialog box appears.Figure 11.12 Parameters dialog box7 Enter the Name and the Value of the parameter. Click OK. The parameter appearsin the Parameters field in the JSP Include Action dialog box.8 To delete or modify a parameter, select the parameter in the Parameters field andclick the Delete button or the Edit button.9 When you have finished entering the desired parameters, click OK.The include action is inserted into your JSP page as the JSP include tags: and If you are passing parameters to the included file, the JSP param tag:appears between the JSP include tags: and11-10 User’ s Guide

JSP include directivesNoteA JSP include action can also be inserted using the Insert|JSP Include Action menuitem.JSP include directivesA JSP include directive is used to include text or code from another file into your JSPpage when it is processed by the server. The included file can contain text, HTML, orJSP code. If the included file contains JSP code, the JSP server translates this code aswell. The included text replaces the include directive, that is, it is a static include. Theincluded file must be accessible by both the JSP page and the JSP server.To insert a JSP include directive into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. >TheObjects palette displays the supported JSP tags.2 Select the Include Directive icon from the Objects palette. The JSP IncludeDirective dialog box appears.Figure 11.13 JSP Include Directive dialog boxNote3 Enter the relative URL of the File to include.4 Click OK.The include directive is inserted into your JSP page, embedded in the includedirective tag (short form) or A JSP include directive can also be inserted using the Insert|Include Directive menuitem.JSP page directivesA JSP page directive is used to define properties and send them to the JSP server.More than one page directive can be included in a translation unit, which includesnot only the JSP file, but also any statically included files. Attributes used in the pagedirectives must be unique, except for imports which are cumulative. The entire set ofpage directives apply to the entire translation unit.To insert a JSP page directive into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the Page Directive icon from the Objects palette. The JSP Page Directivedialog box appears.Dreamweaver UltraDev Plug-in 11-11

JSP page directivesFigure 11.14 JSP Page Directive dialog boxThe JSP Page Directive dialog box has the following fields:ExtendsImportSessionBuffer (kb)AutoFlushIsThreadSafeInfoErrorPageIsErrorPageContentTypePageEncodingThe parent class of the servlet generatedfrom the JSP. (Rarely necessary!)Java classes accessed by the JSP page.If ”true” the page has an implicit sessionvariable.The minimum size of the output bufferof the JSP page, expressed in kb, or”none” for direct output.If ”false” raises an exception on bufferoverflow.If ”false” ensures client requests areprocessed one at a time.An arbitrary string associated with thegenerated servlet.The URL of the page handling thrownobjects not caught by this page.If ”true” the page has an implicitexception variable.The character encoding for the JSP pageand its response, and the MIME type ofthe response.The character encoding for the JSP page(overriding the specification incontentType).1 Enter the information you require. (Since the only acceptable value for the(scripting) Language attribute is ”java”, this field is not displayed.)2 Click OK.The page directive is inserted into your JSP page embedded in the JSP page directivetag11-12 User’ s Guide

JSP Plug-in actionsNote (short form) or A JSP page directive can also be inserted using the Insert|JSP Page Directive menuitem.JSP Plug-in actionsA JSP plug-in action is used to generate client-appropriate HTML code which causesthe client's web browser to download the plug-in where necessary and execute thespecified component. When the JSP page is processed, the plug-in action is replacedby either an element (HTML 3.2) or element (HTML 4.0), dependingon the user's web browser version. A JSP plug-in can be either an Applet or aJavaBean component. Parameters can be passed to the component.To insert a JSP plug-in action into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the Plugin Action icon from the Objects palette. The JSP Plugin Actiondialog box appears.Figure 11.15 JSP Plugin Action dialog boxThe JSP Plugin Action dialog box includes the following plug-in attribute fields:TypeCodeCodebaseAlignArchiveHeightComponent: Bean or AppletThe content type of the componentThe base path of relative URIsThe position of the component relative toits contextURIs of resources used by thecomponentThe height of the componentDreamweaver UltraDev Plug-in 11-13

JSP Plug-in actionsHspaceJreversionNameVspaceWidthNspluginurlIepluginurlThe white space left and right of thecomponentThe version of the JRE required by thecomponentThe control name of the componentThe white space above and below thecomponentThe width of the componentThe URL where a JRE plugin can bedownloaded for Netscape NavigatorThe URL where a JRE plugin can bedownloaded for Internet Explorer1 Enter the information for the attributes you require.2 Enter any Parameters you need to pass to the Applet or JavaBean. To add aparameter, click the New button. The Parameters dialog box appears.Figure 11.16 Parameters dialog boxNote3 Enter the Name and the Value of the parameter. Click OK.The parameter appears in the Parameters field in the JSP Plugin Action dialog box.To delete or modify a parameter, select the parameter in the Parameters field andclick the Delete button or the Edit button.4 Enter the Fallback Text that must appear if the plug-in cannot be started.5 Click OK.The plug-in action is inserted into your JSP page as the JSP plugin tags: and The fallback tags: and appear between the two plug-in tags, as does the JSP param tag:for any parameters specified.A JSP plug-in action can also be inserted using the Insert|JSP Plugin Action menuitem.11-14 User’ s Guide

JSP scriptletsJSP scriptletsA JSP scriptlet is a short piece of code used to manipulate Java objects and tocalculate values. The code must conform to the syntax and semantics of the scriptinglanguage. The scriptlet is executed when the JSP server processes the JSP page.To insert a JSP scriptlet into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the Scriptlet icon from the Objects palette. The JSP Scriptlet dialog boxappears.Figure 11.17 JSP Scriptlet dialog boxNote3 Enter the Java Scriptlet you want executed.4 Click OK.The scriptlet is inserted into your JSP page between the JSP scriptlet tags (short form) or and A JSP scriptlet can also be inserted using the Insert|JSP Scriptlet menu item.JSP setProperty actionsA JSP setProperty action sets a property value within a Bean instance. The definitionof the Bean must appear before the JSP setProperty action is used, and within the file.The instance of the Bean must contain the property you want to set. There are threedifferent syntaxes for the setProperty action.To insert a JSP setProperty action into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the setProperty Action icon from the Objects palette.Dreamweaver UltraDev Plug-in 11-15

JSP taglib directivesThe JSP setProperty Action dialog box appears.Figure 11.18 JSP setProperty Action dialog boxNote3 Select the Syntax you want to use from the drop-down list.The fields displayed in the dialog box depend on the syntax chosen.4 Enter the Name of the Bean instance. This Name refers to the same name used inthe useBean action's ID field when the Bean was defined.5 Enter the name of the Property you want to set.6 Depending on the syntax chosen:• Enter the name of the Parameter whose value you want to assign to theproperty.• Enter the Value to assign to the property.7 Click OK.The setProperty action is inserted into your JSP page embedded in the JSPsetProperty tag A JSP setProperty action can also be inserted using the Insert|JSP setProperty Actionmenu item.JSP taglib directivesA JSP taglib directive is used to declare a tag library for the JSP page. A taglib uses aURI to define the tag library. The prefix used should follow XML namespacespecifications. An error occurs if the tag library cannot be found or if the taglibdirective appears after any occurrences of the prefix.To insert a taglib directive into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the Taglib Directive icon from the Objects palette. The JSP TaglibDirective dialog box appears.11-16 User’ s Guide

JSP useBean actionsFigure 11.19 Taglib Directive dialog boxNote3 Enter the URI for the tag library, and the Prefix you want to use.4 Click OK.The taglib directive is inserted into your JSP page embedded in the taglib tag:A JSP taglib directive can also be inserted using the Insert|JSP Taglib Directive menuitem.JSP useBean actionsA JSP useBean action is used to locate an instance of a Bean, or create an instance of aBean. A useBean action first searches for an instance of the specified Bean within thespecified scope. If the instance is not found, it creates an instance of the Bean from theclass specified. If a new instance of the Bean is created, any body tags or elementsbetween the useBean's start and end tags are executed. If the Bean is simply located,any body tags and elements between the useBean's tags are ignored.To insert a JSP useBean action into your JSP page:1 In the Dreamweaver Objects palette, select JSP from the drop-down menu. TheObjects palette displays the supported JSP tags.2 Select the useBean Action icon from the Objects palette. The JSP useBeanAction dialog box appears.Figure 11.20 JSP useBean Action dialog box3 Select the Syntax you want to use from the drop-down list.The fields displayed in the dialog box depend on the syntax chosen.4 Enter the ID of the Bean you want to locate, as well as the Scope.Dreamweaver UltraDev Plug-in 11-17

JSP useBean actionsNote5 Depending on the syntax chosen:• Enter the name of the Class of the Bean.• Enter the name of the Bean that is required by the instantiate() method.• Enter the Type of the defined scripting variable.• Enter any Body tags or elements to be executed if a new instance of the Bean iscreated.6 Click OK.The useBean action is inserted into your JSP page as the JSP useBean tags: and Any body tags and elements appear between these two tags.A JSP useBean action can also be inserted using the Insert|JSP useBean Action menuitem.11-18 User’ s Guide

IndexSymbols... ellipsis 1-3| vertical bar 1-3Numerics2PC Transaction Service 3-12, 3-40AAbout command 2-6activationEJBs 3-29add button 9-26addingdatasources 9-41descriptor information 9-5session bean 9-23Address File 2-16agentaddr file 2-16Apachecreating managed Apache 5-3Apache web server 3-12configuration properties 3-41configuring 3-12shared service 3-41APIsJ2EE supported 3-10application assembler 9-29Application Assembly tool 8-1adding files 8-3creating an archive file 8-6editing a text file 8-4editing an archive file 8-5extracting modules 8-7modifying an archive file 8-5opening an archive 8-3saving an archive file 8-5starting 8-2verifying an archive file 8-8application developer 3-26, 9-29Apply Patch Wizard command 2-5archiveattributes 3-18exploded 3-18hosted 3-18archive fileextracting files from 8-7verifying 8-8archive files 8-1verifying 7-9archive_directory_structures 9-2archivesDARs 9-9hosted 3-6ASP translatorsin Dreamweaver 11-2assembly 9-26Assembly Tool command 2-5authentication 9-14, 9-22, 9-31security configuration 6-2authentication method 9-14authorizationrole reference 6-6rolemap 6-3roles 6-5rules 6-5security configuration 6-3authorization domain 9-13autodiscovery 2-7Axis serviceelements 3-20Bbean informationadding 9-12changing 9-12in deployment descriptor 9-25bean menu 9-23bean statesEJB 3-31bean-managed persistence 3-26, 9-39Borland Community 7-17Borland Developer Network 7-17Borland Developer Supportcontacting 1-3Borland Enterprise Server Home Pagecommand 2-6Borland Enterprise Server News Groupcommand 2-6Borland Management Consolehow to use 2-1starting 2-2Borland Management Service 5-1agents 5-2hub 5-2Borland Technical Supportcontacting 1-3Borland Web site 1-3, 1-5Borland-specific DTDIndex I-1

application 1.3 9-48brackets 1-3buttonsadd 9-26Cchange permissions scriptiaschangeowner 10-11class loading tab 3-17class name 9-25classesin libraries 3-22classloaderpolicy 3-17properties 3-17client-side stub filegenerating 10-10Clone command 3-2cluster wizard 5-7Cluster Wizard command 2-5clusterscreating and defining 5-7deploying JAR files 10-4JDataStores 5-5SonicMQ 5-6undeploying JAR files 10-28using the wizard 5-7viewing 5-1web server 5-3clusters view 5-1, 5-3adding servers 5-14cluster wizard 5-7editing cluster definitions 5-14JDataStores 5-5SonicMQ 5-6starting 5-1viewing statistics and other information 5-15web servers 5-3CMP 7-10CMP 1.1 9-39command line toolscompilejsp 10-2compress 10-3deploy 10-4dumpstack 10-7genclient 10-8gendeployable 10-9genstubs 10-10info 10-13kill 10-13listpartitions 10-15listservers 10-16listservices 10-17merge 10-18migrate 10-19patch 10-19ping 10-20removestubs 10-22restart 10-22start 10-24stop 10-26uncompress 10-27undeploy 10-28usage 10-29verify 10-30commandsConsole menu 2-4conventions 1-3for editing 2-11Help menu 2-6ias 2-12, 2-13, 2-14iconfig 2-15new 9-5new session bean 9-23open 9-5remove 3-21Tools menu 2-5View menu 2-5Wizards menu 2-5communityBorland Community 7-17compilejspiastool command 10-2compressiastool command 10-3compressingfiles in a JAR 7-17configurationof a server 2-13configuration filesviewing and editing 4-1Configure command 3-2connector container services 3-9, 3-28connectorsweb container 3-38ConsoleContent pane 3-1how to use 2-1Installations view 4-1menu commands 2-4Navigation pane 3-1patch display 3-14preferences 2-7Servers view 3-1Servers view tabs 3-1setting preferences 2-7starting 2-2I-2 User’ s Guide

Console menu commands 2-4Console preferencesDiscovery tab 2-8General tab 2-7Logs tab 2-10Security tab 2-9State tab 2-9Statistics tab 2-10Tools tab 2-11containerremoving modules 3-21container folder 3-21container servicesedit 3-27container-managed persistence 3-26, 9-39CMP 1.1 9-39containersEJB properties 3-28Content pane 4-1context menu commandsin Servers view 3-2creatingDARs 9-9JNDI definitions modules 9-9Security Roles 9-36cross tablesadding 9-46many-to-many relationships 9-46Ddatabasemultiuser 9-42database column 9-39database table 9-39datasources 3-26adding 9-41defining 9-41login information 9-41specifying a new 9-41datasources folder 9-36DDEditoraccess tab 9-37adding descriptors 9-5authorization domain 9-13Borland-specific deployment descriptors 9-47creating a JNDI definition descriptor 9-8creating descriptors 9-7creating EAR descriptors 9-12creating WARs 9-13deployed modules 9-5EJB Designer 9-42JARs 9-21jndi definitions archives 9-9many-to-many relationships 9-46method permissions 9-37starting 9-5Table Reference Editor 9-45usage 9-2Vendor tab 9-47WARs 9-14web services 9-21XML 9-2DDEditor command 9-5Delete command 3-2deployiastool command 10-4deployable JAR files 7-15deployed moduleattributes 3-18details tab 3-18general tab 3-18reference tab 3-18xml tab 3-18deployed modulesattributes 3-18DARs 9-9DDEditor 9-5edit deployment descriptor 9-5exploded archives 3-18general tab 3-18deployment 9-26modules 7-2processes 7-3Deployment Descriptordefined 9-5deployment descriptor 3-26, 7-3about 9-2creating new 9-5Deployment Descriptor Editor command 2-5, 2-6deployment descriptor elementsnew 9-48deployment descriptorsBorland DTDs 9-47Borland-specific 9-47, 9-48Vendor tab 9-47deployment role 9-36deployment wizard 7-3Deployment Wizard command 2-5Developer Network 7-17Developer Supportcontacting 1-3Developer's Guide command 2-6diagnostic toolsdumpstack (iastool) 10-7dirty read transaction violation 9-42Disable command 3-2Discovery tabIndex I-3

Console preferences 2-8discovery, of servers 2-7distributableWAR property 9-14documentation 1-1.pdf format 1-1accessing Help Topics 1-2Developer's Guide 1-2Installation Guide 1-2on the web 1-5platform conventions used in 1-3type conventions used in 1-3updates 1-1User's Guide 1-2VisiBroker Developer's Guide 1-2VisiBroker GateKeeper Guide 1-2VisiBroker Programmer's Reference 1-2VisiBroker VisiNotify Guide 1-2Download copy of module command 3-2DreamweaverASP translators 11-2configuring for JSP extension 11-2HTML comments 11-4JSP declarations 11-5JSP expressions 11-6JSP forward actions 11-7JSP getProperty actions 11-8JSP hidden comments 11-9JSP include actions 11-9JSP include directives 11-11JSP page directives 11-11JSP Plug-in actions 11-13JSP scriptlets 11-15JSP setProperty actions 11-15JSP taglib directives 11-16JSP useBean actions 11-17scriptlets 11-15Dreamweaver UltraDev Plug-in 11-1DTDsBorland-specific 9-48new 9-48dumpgenerating 10-7dumpstackiastool command 10-7EEAR filedefinition 3-20viewing 3-20EAR files 7-6attributes 3-23EARsadding 9-12properties 9-12Edit with assembly tool command 3-2Edit with deployment descriptor editorcommand 3-2editing commands 2-11EJBactivation 3-29and JAR file 3-24bean states 3-31container properties 3-28dispatching 3-29exporting a stateless session bean as a Webservice 7-18exporting a Web Service 7-18statistics 3-29viewing 3-24EJB 2.0relationships 9-45EJB Container 9-41EJB containerabout 3-24adding a transaction 9-33attributes 3-27multiple 3-26Partition Service 3-8, 3-28transactions 9-33EJB container servicesabout 3-26EJB containersdeployable modules 3-26EJB Designer 9-42adding cross tables 9-46Borland Enterprise Server implementationof 9-42Table Reference Editor 9-45EJB link 9-15EJB persistence1.0 3-262.0 3-26EJB Reference 9-39EJB referencesdeployment descriptor 9-15example deployment descriptor 9-15EJB References panel 9-27EJB specification 3-26Enable command 3-2engineweb container 3-36Enterprise Archives (EARs) 3-20enterprise beanentity beans 3-25stateful session 3-25stateless session 3-25I-4 User’ s Guide

enterprise beansdeploying 7-2in deployment descriptor 9-23JNDI name 9-23logical name 9-23naming 9-23Entity beans 9-41entity beans 3-25, 9-25, 9-39reentrant 9-25environment entries 9-26environment panel 9-26environment variables 2-13error log 3-13event log 3-13generating a stack trace 10-7executing iastool from a script 10-31Exit command 2-4exploded archive 3-18exploded archives 3-18export EJB as a Web Service wizard 7-18extractingfiles from a JAR 7-17extracting modules 8-7Ffactory referencesenterprise beans 9-14, 9-22factory references, for enterprise beans 9-31factory statesVisiConnect 3-34File menu 9-5-file optionexecuting iastool from a script 10-31, 10-32file optionexecuting iastool from a script 10-32file permissionsiaschangeowner 10-11options 10-11filesagentaddr 2-16localaddr 2-15filter mappingsweb application 9-19finders panel 9-40Ggenclientiastool command 10-8gendeployableiastool command 10-9General panelsession bean information 9-25General tabConsole preferences 2-7Generate client jars command 3-2genstubsiastool command 10-10HHelp menu commands 2-6hit rateTomcat web container 3-35web container 3-35home interface 9-14, 9-22, 9-25, 9-27, 9-31, 9-33,9-37home interfaces 7-12hostweb container 3-37hosted archive 3-18hosted archives 3-6hosted from server path 3-18hosted modules 3-6hosted Partition 3-6HTML browser 2-7HTML commentswith Dreamweaver 11-4Hub 5-2Iias command 2-12, 2-13options 2-14ias.config file 2-14iaschangeowneroptions 10-11rules 10-12usage 10-12-iastoolexecuting from a script 10-31iastoolcompilejsp 10-2compress 10-3deploy 10-4dumpstack 10-7genclient 10-8gendeployable 10-9genstubs 10-10iaschangeowner 10-11info 10-13kill 10-13listpartitions 10-15listservers 10-16listservices 10-17merge 10-18migrate 10-19patch 10-19ping 10-20Index I-5

emovestubs 10-22restart 10-22start 10-24stop 10-26uncompress 10-27undeploy 10-28usage 10-29verify 10-30iconfig command 2-15IIOP connectorand Apache log 3-41infoiastool command 10-13Installation Guide command 2-6installation information 3-15Installations view 4-1interface column 9-33interfaceshome 7-12remote 7-12IP address 2-15, 2-16ISLink 9-14, 9-22isolation levels 9-41, 9-42JJ2EEDDEditor 9-2J2EE APIsJava DataBase Connection 3-10Java Mail 3-10Java Naming and Directory Interface 3-11JAXP 3-11JMS 3-13, 3-41JTA 3-11RMI-IIOP 3-11supported 3-10J2EE Deployment 7-2J2EE modulesdeployment 7-2JAR Filesand EJBs 3-24JAR files 9-5compressing 7-17converting 7-10creating a deployable JAR 7-15deploying 10-4extracting 7-17generation 7-6information 3-23migrating 7-10server-side deployable 10-9undeploying 10-28viewing 3-23JAR wizard 7-17Jar Wizard command 2-5JARsproperties 9-21Java Development Kit (JDK) 11-1Java Mail 3-10Java Messaging ServiceSoniqMQ 3-13, 3-41Java Naming and Directory Interface 3-11Java Runtime Environment (JRE) 11-1Java Server Pagesprecompiling 10-2Java Session Service 3-8Partition Service 3-33Java Transactional API 3-11java2iiop argument list 10-6JAXP 3-11JDataStore 3-26configuration properties 3-32creating managed JDataStore 5-5Partition Service 3-8, 3-32JDataStore Explorerstarting 3-8JDataStore Explorer command 2-5JDBC 3-10JDBC datasources 9-8JDBC driver 9-41JMSSoniqMQ 3-13, 3-41JNDI 3-11, 9-14, 9-22, 9-27, 9-31starting the browser 3-11JNDI Browser command 2-5JNDI definition descriptor 9-8JNDI definitions 9-8JNDI definitions archivesDARs 9-9JNDI definitions modulesexamples in Borland Enterprise Server 9-12JNDI object 9-8JNDI references 7-6JSP declarationswith Dreamweaver 11-5JSP expressionswith Dreamweaver 11-6JSP extensionwith Dreamweaver 11-2JSP fileTomcat web container 3-35web container 3-35JSP forward actionswith Dreamweaver 11-7JSP getProperty actionswith Dreamweaver 11-8JSP hidden commentsI-6 User’ s Guide

with Dreamweaver 11-9JSP include actionswith Dreamweaver 11-9JSP include directiveswith Dreamweaver 11-11JSP page directiveswith Dreamweaver 11-11JSP Plug-in actionswith Dreamweaver 11-13JSP scriptletswith Dreamweaver 11-15JSP setProperty actionswith Dreamweaver 11-15JSP taglib directiveswith Dreamweaver 11-16JSP useBean actionswith Dreamweaver 11-17JSSPartition Service 3-8, 3-33JTA 3-11Kkilliastool command 10-13Kill command 3-2Korn shell 2-12Llast accessedTomcat web container 3-35web container 3-35librariesabout 3-22attributes 3-22deployed 3-22viewing 3-22library modulesPartition lifecycle interceptors 3-19XML tab 3-19licenseupdate 2-2licensingManagement Console 2-2Linux requirementsrunning BES on 2-12listenersDDEditor 9-20WARs 9-20listpartitionsiastool command 10-15listserversiastool command 10-16listservicesiastool command 10-17load orderTomcat web container 3-35web container 3-35load state 9-40Local File 2-15localaddr file 2-15Location Service 2-7logging levelfor security 6-2logical nameenterprise beans 9-23Login command 2-4login informationprotecting 10-31running from a script file 10-31Logout command 2-4logserror 3-13event 3-13viewing 3-13Logs tabConsole preferences 2-10MManagement Agent 5-2Management Consoleclusters view 5-1Content pane 3-1how to use 2-1Installations view 4-1Navigation pane 3-1patch display 3-14Servers view 3-1Servers view tabs 3-1starting 2-2Management Hub 5-2management port 2-7, 7-17manifest fileApplication Assembly tool 8-2membershipBorland Community 7-17menu commands 2-4menusbean 9-23File 9-5Tools 9-5type 9-26mergeiastool command 10-18merge wizard 7-6Merge Wizard command 2-5message lines, in log file 2-7Index I-7

message-driven bean panel 9-32Messages command 2-5method permissions 9-37, 9-41assigning 9-41DDEditor 9-37method parameters 9-38methods column 9-33migrateiastool command 10-19migrating JAR files 7-10MIMEmapping extension and mime type 9-18type 9-18mime type 9-14mobility settingsdeployed 3-18hosted archives 3-18moduledeployable 3-26deployed 3-18removing 3-21moduleshosted 3-6multiple network interfaces 2-15Nnameenterprise beans 9-23, 9-25Naming ServicePartition Service 3-8, 3-32Navigation pane 4-1, 9-3, 9-36network interfaces, multiple 2-15new command 9-5New Partition command 3-2Newsgroups 1-5non-repeatable read transaction violation 9-42OOnline Helpaccessing 1-2open command 9-5OptimizeIt Profilerenabling on a Partition 3-9installing 3-9setting up 3-9starting 3-10Tools tab 2-11OptimizeIt Profiler command 2-5PpanelsEJB References 9-27environment 9-26finders 9-40Persistence 9-31persistence 9-41Resource References 9-31Security Role References 9-29Partitionassembling a footprint 3-6cloning 3-5configuring 3-5configuring server to manage 3-7configuring server to run 3-7creating 3-5creating an explicitly-pathed 3-6enabling OptimizeIt Profiler 3-9explicitly-pathed 3-6hosted 3-6naming 3-6properties 3-15, 3-16running a standalone 3-7running explicitly pathed 3-7security properties 3-16security settings 3-16shared services 3-12, 3-40start order 3-6two-phase commit Transaction Service 3-12,3-40VisiTransact 3-12Partition lifecycle interceptors 3-19Partition Services 3-4EJB container 3-8, 3-9, 3-28JDataStore 3-8, 3-28, 3-32JSS 3-8Naming Service 3-8, 3-28, 3-32OptimizeIt Profiler 3-9, 3-28Session Service 3-8, 3-28, 3-33starting JDataStore Explorer 3-8Tomcat web container 3-9Transaction Service 3-8, 3-28, 3-33VisiConnect Service 3-9, 3-28, 3-34web container 3-9, 3-35Partition services 3-26view 3-27Partitionsdeploying JAR files 10-4overview 3-4undeploying JAR files 10-28partitionsconfiguring security for 6-1Performance Tuning Wizard 7-17password informationprotecting 10-31running from a script file 10-31patchI-8 User’ s Guide

iastool command 10-19viewing details 3-14patch displayread-me 3-14patch wizard 7-17patchesapplying 7-17PDF documentation 1-1performance monitoringbean states 3-31EJB statistics 3-29Factory States 3-34Performance tuning command 3-2Performance Tuning Wizard 7-17permissions commandiaschangeowner 10-11persistence 3-25, 3-26, 7-3Persistence panel 9-31persistence panel 9-14, 9-41phantoms transaction violation 9-42pingiastool command 10-20Ping command 3-2ping intervalstatus 2-7polling interval 2-7performance information 2-7statistics 2-7port configuration wizard 7-17portsmanagement port 7-17user port 7-17precompiling JSPs 10-2preferencesConsole 2-7Discovery tab 2-8General tab 2-7Logs tab 2-10Security tab 2-9State tab 2-9Statistics tab 2-10Tools tab 2-11user interface 2-7Preferences command 2-4primary key 9-25product information 3-15propertiesserver configuration 3-14property column 9-26property filesviewing and editing 4-1property types 9-26RRAR filesabout 3-22attributes 3-23RARsviewing 3-23realm informationprotecting 10-31running from a script file 10-31Redeploy command 3-2reentrant beans 9-25Refresh command 2-4Register Server command 3-2registeringBorland Community Member 2-3Borland Enterprise Server 7-17by phone 2-3Management Console 2-2online 2-3quick registration 2-3Software Registration Account 2-3registration wizard 7-17remote interface 9-25, 9-27, 9-33, 9-37remote interfaces 7-12remove stubs wizard 7-16removestubsiastool command 10-22Resource Adapter Archives (RARs) 3-22resource adaptersviewing 3-23resource env refsDDEditor 9-20resource referencesweb applications 9-18Resource References panel 9-31response timeTomcat web container 3-35web container 3-35restartiastool command 10-22Restart command 3-2RMI-IIOP 3-11rolemapauthorization 6-3roles 6-5role reference 6-6roles 6-5rules 6-5Sscript file-file option 10-32Index I-9

passing a file to iastool 10-32piping a file to iastool 10-31running iastool utilities from 10-31scriptletswith Dreamweaver 11-15securityauthentication 6-2authorization 6-3configuring in the Console 6-1domain 6-3logging level 6-2method permissions 9-37Partition settings 3-16role reference 6-6rolemap 6-3roles 6-5rules 6-5Security Role References panel 9-29Security Roles 9-29about 9-35security roles 7-3authorization domain 9-13creating 9-36deployment role 9-36Security tabConsole preferences 2-9serverconfiguration properties 3-14configuring from the command line 2-13configuring to manage a Partition 3-7configuring to run a Partition 3-7configuring using the Console 2-13description 3-14starting from the command line 2-12starting from the Windows Desktop 2-12starting using the Console 2-12stopping 2-13viewing properties 3-14Servers viewcontext menu commands 3-2server-side stub filegenerating 10-10servicestop-level 4-1servlet classTomcat web container 3-35web container 3-35servlet mapping 9-19session beans 9-25adding 9-23Session Serviceconfiguration properties 3-33Partition Service 3-8, 3-33session type 9-25shared servicesApache web server 3-12, 3-41Java Messaging Service 3-13, 3-41JMS 3-13, 3-41Smart Agent 3-12, 3-41SonicMQ Broker 3-13, 3-41Transaction Service 3-40VisiTransact 3-12Smart Agent 2-15, 3-12configuration properties 3-41configuring 3-12shared service 3-41Softwareupdates 1-5Sonic JMS object 9-8SonicMQconfiguration properties 3-41configuring 3-13creating a managed SonicMQ 5-6launching 3-13shared service 3-41starting 3-13SonicMQ Explorer command 2-5SoniqMQ 3-13, 3-41SQL where clause 9-40square brackets 1-3stack tracegenerating 10-7startiastool command 10-24start button 9-5Start command 3-2startingthe Management Console 2-2starting a default server 2-17starting a server 2-12from the command line 2-12from the Windows Desktop 2-12Linux requirements 2-12using the Console 2-12State tabConsole preferences 2-9stateful session bean 3-25stateless session bean 3-25exporting as a Web Service 7-18statisticsEJB 3-29polling interval 2-7Tomcat web container 3-35web container 3-35Statistics tabConsole preferences 2-10statuspolling interval 2-7I-10 User’ s Guide

Status bar command 2-5status messages 3-13stopiastool command 10-26Stop command 2-13, 3-2stoppinga server 2-13stub filegenerating 10-10Stub Generation Wizard command 2-5stubsgenerating 7-12generation wizard 7-12non-container applications 7-12removing 7-16stubs only library 7-14stubs librarycreating 7-14Supportcontacting 1-3symbolsellipsis ... 1-3vertical bar | 1-3system configuration information 10-13TTable Reference Editoradding cross tables 9-46specifying references 9-45tag librariesweb application 9-19TCP/IP protocol 2-15Technical Supportcontacting 1-3thread dumpgenerating 10-7Tomcat web container 3-28configuring properties 3-36connector tab 3-38engine tab 3-36hit rate 3-35host tab 3-37JSP file 3-35last accessed 3-35load order 3-35loaded 3-35Partition Service 3-9response time 3-35server statistics tab 3-35servlet class 3-35statistics 3-35Tool bar command 2-5Tools menu commands 2-5Tools tabConsole preferences 2-11top-level services 3-1transactionadding 9-33isolation levels 9-42transaction policies 7-3, 9-33transaction policyTX_BEAN_MANAGED TransactionPolicy 9-33TX_MANDATORY 9-33TX_NOT_SUPPORTED 9-33TX_REQUIRED 9-33TX_REQUIRES_NEW 9-33TX_SUPPORTS 9-33Transaction Serviceconfiguration properties 3-33Partition Service 3-8, 3-33transaction serviceconfiguration properties 3-40transaction type 9-25transaction violations 9-42transactions 9-33, 9-41EJB Container 9-33troubleshooting 3-13tuningPerformance Tuning Wizard 7-17two-phase commitconfiguration properties 3-40two-phase commit Transaction Service 3-12, 3-40type menu 9-26UUltraDev Plug-in 11-1uncompressiastool command 10-27undeployiastool command 10-28Update License command 3-2Update ports command 3-2updatespatch display 3-14URL locationdatasources 9-41usageiastool command 10-29user interfacepreferences 2-7user port 7-17User's Guide command 2-6Vvalue column 9-26Index I-11

vendor deployment descriptorcross table 9-46Vendor tab 9-48verifyiastool command 10-30verify wizard 7-9Verify Wizard command 2-5verifying an archive file 8-8View menu commands 2-5VisiBroker Consolestarting 2-17VisiBroker Developer's Guide command 2-6VisiBroker DocumentationVisiNotify Guide 1-2VisiBroker documentationDeveloper's Guide 1-2GateKeeper Guide 1-2Programmer's Reference 1-2VisiBroker Programmer's Reference command 2-6VisiConnectfactory states 3-34performance monitoring 3-34VisiConnect Serviceconfiguration properties 3-34Partition Service 3-9, 3-28, 3-34VisiNotify Guide command 2-6VisiTransact Transaction Manager 3-12WWAR filesabout 3-21precompiling Java Server Pages 10-2viewing 3-21Web Archives (WARs) 3-21web containerabout 3-28configuration properties 3-35configuring properties 3-36connector tab 3-38engine tab 3-36hit rate 3-35host tab 3-37JSP file 3-35last accessed 3-35load order 3-35loaded 3-35Partition Service 3-9response time 3-35server statistics tab 3-35servlet class 3-35statistics 3-35web deploy paths 9-20DDEditor 9-20IIOP connector 9-20web server 3-12configuring 3-12Web Services 9-21Web servicesexporting a stateless session bean as 7-18exporting an EJB as 7-18Welcome filesweb application 9-19where clauseSQL 9-40Windows NT 9-5Wizards 7-1Performance Tuning 7-17wizardsapply patch 7-17deployment 7-3export EJB as a Web Service 7-18JAR 7-17merge 7-6port configuration 7-17registration 7-17remove stubs 7-16stubs generation 7-12verify 7-9XML migration 7-10Wizards menu commands 2-5Work pane 9-3World Wide WebBorland documentation on the 1-5Borland newsgroups 1-5Borland updated software 1-5XXMLDDEditor 9-2find and replace 9-2go to 9-2parsing APIs 3-11vendor tab 9-48XML editor 9-2XML files 9-5XML migration wizard 7-10XML Migration Wizard command 2-5XML tab 3-19I-12 User’ s Guide