Trifork Enterprise Application Server. Userguide

Transcription

1 Trifork Enterprise Application Server Userguide

2 Trifork Enterprise Application Server: Userguide Copyright Trifork Technologies

3

4 Table of Contents I. New features New features in release II. Getting started The 20 minutes guide to the Trifork server Download Installation Starting the server Prepare an application for deployment Deploying the application Accessing the deployed application Simple management Configuring data sources HTTP endpoints... 6 III. Overview of the Trifork platform Introduction to the J2EE platform J2EE Platform Overview Component Types Enterprise Java Beans (EJB) Servlets Java Server Pages (JSP) J2EE Containers Component Services Network Communication Technologies JDBC JNDI JTA JavaMail Trifork Enterprise Application Server Platform Concepts Node System Container Domain Domain Types Single Server Domain Domain with multiple servers How to create a domain Ways to manage servers Trifork Management Client Trifork Command Line Tools Trifork Ant Tasks Domain Configuration Data Architecture and features of the Trifork Enterprise Application Server Main Architectural Patterns Microkernel Architecture ORB Module Naming Module Transaction Manager Module Security Module Repository Module JDBC Pool Module Log Module Management Module Thread Pool Module System Manager Module System Container Module EJB Container Module Web Container Module iv

5 Trifork Enterprise Application Server IV. Installation Preparing the installation Downloading the Trifork Enterprise Application Server Handling the 30 day trial license key Preparing a directory for installation Installing on Windows Normal installation Step-by-step guide Installing Trifork Enterprise Application Server as a Windows Service Installing on Unix Starting the server for the first time Installing the license key Creating a new domain Starting and stopping the server Server start modes Starting the Trifork Enterprise Application Server from Windows Verifying that the server is running Changing the administrator password Making a permanent login on the server Deploying and running the example applications The Java Pet Store Sample Application V. Configuring and managing the Trifork Enterprise Application Server Domains Creating a domain Domain directory layout bin lib logs config client-config servers applicationrepository and preferences Configuration The trifork management client HTTP Configuring an existing endpoint Creating a new endpoint Data sources CMP type mappings JDBC Data Sources Pooled Data Sources JMS Connection Factories Destinations Mail Security Realms Creating Security Realms Managing Security Realms Threadpool EmbeddedDB System Containers Creating System Containers Managing System Containers Log Settings Configuring server logging Configuring Application Client Logging Configuring the Trifork Command Line Tool Logging Relocating Server Ports Command Line Tools Web Server Integration Configuring Web Server Integration Configuring the Trifork Enterprise Application Server Configuring the Web Server v

6 Trifork Enterprise Application Server 14. Public Web Application Default Deployment Descriptor Monitoring a Running Server Server Monitor Statistics J2SE Application Client Administration Stopping clients Broadcasting Messages Application Client Implementation Requirements Monitoring Connected Clients Default Listing Extended Listing Configuration properties VI. Deploying to the Trifork Enterprise Application Server Overview Setting up the Development Environment Packaging J2EE applications Trifork Specific Archive Formats Inflated Archives Mapped Archives JAR Files Packaging Web Components Packaging EJB Components Packaging J2EE Application Clients Packaging Connectors Packaging Enterprise Applications Trifork Deployment Descriptor Configure global resources (users and datasources) Binding EJBs and Resources Referencing EJBs in the Current Archive Referencing EJBs Outside the Current Archive Setting up a JDBC Resource References Setting and Overriding env-entry's Configuring Web Applications Enabling Persistent Web Sessions Setting the Context Root for a Web Application Setting up HTTP Endpoints Packaging Connectors Example Configuring Security Roles Deploying Archives Creating a System Container Deploying Applications to the Trifork Server Deploying an Application Redeploying an Application Undeploying an Application Hot Deploy Specifying the trifork-app-conf.xml Inplace Deployment Automatic Redeploy Precompilation of JSP Files Validation of XML Syntax Working with a Remote Server Running a Web Client Deploying and Running J2EE Application Clients Deploying an Application Client Running an Application Client Setting J2EE Application Client Properties Deploying and Running Clients Without Client Container Generating RMI-IIOP Stubs Connecting to the Trifork Enterprise Application Server From a Client VII. The Trifork Assembly tool Introduction... vi

7 Trifork Enterprise Application Server Starting the Trifork Assembly Tool Workspace Layout Main Menu Toolbar Tree View Common Functionality of Popup Menus Enterprise Archive EJB JAR Archive Web Archive Application Client Enterprise JavaBean Java Server Page Servlet Error and Warning Area Tool Log Infobar Assembling a Simple J2EE Application Creating the Basic Structure Adding an Enterprise Java Bean Adding the Web Components Adding a Server Deploying an Application Running the Application Component Management Enterprise Archives Inspect Classpath EJB JAR archives Inspect Classpath Principals Web archives Details Inspect Listeners Java:comp Context Params Mime mapping Roles/Principals Security Enterprise java beans General Interfaces Details Java:comp Transaction settings Persistence Web Components General Init param Security Deployment Descriptors Server Management Adding a Server Connecting to a Server General Server Management VIII. Trifork tools The Trifork command line tools archive trifork archive convert trifork archive deploy trifork archive undeploy assembly vii

8 Trifork Enterprise Application Server trifork assembly start auth trifork auth login trifork auth logout client trifork client listclients trifork client publishmessage trifork client run trifork client stopclients compile trifork compile jspc domain trifork domain create trifork domain export trifork domain import trifork domain remove http trifork http createendpoint trifork http removeendpoint jdbc trifork jdbc createdatasource trifork jdbc createpooleddatasource trifork jdbc removedatasource trifork jdbc removepooleddatasource jms trifork jms createqueuefactory trifork jms createqueue trifork jms createtopicfactory trifork jms createtopic trifork jms removedestination trifork jms removefactory mail trifork mail createconfiguration trifork mail removeconfiguration management trifork management client realm trifork realm addgroup trifork realm addmember trifork realm adduser trifork realm create trifork realm listgroup trifork realm list trifork realm listuser trifork realm remove trifork realm removegroup trifork realm removemember trifork realm removeuser trifork realm updateuser server trifork server create trifork server export trifork server import trifork server remove trifork server start trifork server stop system trifork system create trifork system list trifork system remove trifork system restart trifork system start trifork system stop viii

9 Trifork Enterprise Application Server 27. The Trifork ant tools Getting started Using your own ant installation archive convert deploy undeploy auth login logout domain create export import remove realm addgroup addmember adduser listgroup list listuser removegroup removemember removeuser updateuser create remove server start stop system create list remove start stop IX. The Trifork Profiler Trifork Profiler Example Profiling an application Starting the profiler Hot spots Views Filters X. Example applications bundled with the Trifork Enterprise Application Server Simple examples Entity Bean using CMP Writing the Entity Bean Writing the Servlet Writing the Deployment Descriptors Building, deploying, and running the example Entity Bean using BMP Writing the Entity Bean Writing the Servlet Writing the Deployment Descriptors Building, deploying, and running the example Session Bean and JSP Writing the Session Bean Writing the JSP page Writing the JavaBean Wrapper Writing the Deployment Descriptors Building, deploying, and running the example Advanced examples... ix

10 Trifork Enterprise Application Server J2EE application client The example application Writing the application client Building and deploying the application Running the application client Application examples Java Pet Store Demo Using the Demo XI. References Trifork System Container XML Descriptor Log4j XML Descriptor Third Party Licenses... x

11 Part I. New features

12 Chapter 1. New features in release 3.3 Since the 3.2 release the Trifork Enterprise Application Server has been extended with a lot of new features. The most important are: LDAP integration: It is now possible to integrate with LDAP servers for security realms. See Section 11.6 for a detailed description on how to use this feature. Hot deployment: Deploy by just copying your archive to a specific directory. See Section for more information. Automatic redeploy: Let the Trifork Enterprise Application Server monitor your deployment and automatically redeploy it when changed. See Section for details. Mapped archives: Tired of packing your archives with jar? Just use mapped archives instead. Go to Section 19.1 for the full explanation. Persistent Web Sessions: See Section for information on how to enable this. Application client management: Manage and monitor application clients connected to a server. See Chapter 16 for information on how to use this feature. 2

13 Part II. Getting started This guide serves as an short introduction to the Trifork Enterprise Application Server. This guide requires previous knowledge about the J2EE standard and J2EE Application Servers

14 Chapter 2. The 20 minutes guide to the Trifork server 2.1. Download A 30 day trial version of the Trifork Enterprise Application Server is available from the Trifork web-site at: Before you can download the server, you need to register with your address. The address will be used for sending your 30 day trial license key. Having registered, you can download the server. A number of different packages are available, depending on your operating system, and whether you want to have a JDK included in the package. At the moment the following operating systems are supported: Windows Server, XP, 2000 and NT Linux - Intel x86, tested on RedHat 7.x, 8 and 9, and SuSE 7.x, 8.x Solaris - SPARC, tested on Solaris 7 and Installation The method of installation depends on which operating system you use: Windows: Execute the exe file and follow the directions given in the installation wizard Linux/Solaris: Unpack the archive to a temporary directory, e.g. /tmp. This will create a directory called trifork-3.2-x. Go to this directory and type./install - then follow the directions given by the wizard. In the following we will use "INSTALLATION_DIRECTORY" as a reference to the directory in which you have chosen to install the server. Shortly after you have downloaded the server you will receive an with a 30 day license key attached. Save this file (license.txt) into the INSTALLATION_DIRECTORY/server/license directory Starting the server The server can be started in both development and production mode. Development mode gives you a number of development features, e.g., better debugging of JSP's, the opportunity to connect to the server using debugging tools, the Trifork Semantic Profiler is started. To start the server, simply go to INSTALLATION_DIRECTORY/domain/default/bin directory and issue the following command for development and production mode respectively: Figure 2.1. Starting the server on Windows INSTALLATION_DIRECTORY\domains\default\bin>startDevelServer-default.cmd OR INSTALLATION_DIRECTORY\domains\default\bin>startProductionServer-default.cmd Figure 2.2. Starting the server on Linux/Solaris 4

15 Chapter 2. The 20 minutes guide to the Trifork server bin]$./startdevelserver-default.sh Or bin]$./startproductionserver-default.sh The server is up and running when you see the line "Server running" in the prompt. You can then access it by using the following URL: A default page is installed here stating the version of the server, and when the server was started Prepare an application for deployment Having started the server it is time to prepare a J2EE application for deployment. This involves two steps: Prepare a J2EE archive with portable descriptors Add a Trifork specific deployment descriptor to the archive A simple J2EE application with portable descriptors TION_DIRECTORY/samples/simpleweb/simpleweb.war can be found in INSTALLA- To add Trifork specific deployment descriptors to this archive, start the Trifork Assembly tool. You do this by going to the INSTALLATION_DIRECTORY/domain/default/bin directory, and issuing the following command: Figure 2.3. Starting the Trifork Assembly tool [devel@trifork bin]$trifork assembly start Now, do the following: Click the New Project button from the tool bar, and select a name for your project Click the Open War button from the tool bar, and select the archive mentioned above Right-click the simplewar node in the tree view, and select Inspect from the popup menu In the Context root field, type in /simple Click the close button Right-click the simplewar node in the tree view, and select Save from the popup menu You now have an archive which is ready to deploy on the server Deploying the application On the Trifork Enterprise Application Server a J2EE application is deployed into a system container. Each Trifork server is initially preconfigured with a default system container. To deploy the application into this system container. Go to TION_DIRECTORY/domain/default/bin directory and issue the following command: 5 the INSTALLA-

16 Chapter 2. The 20 minutes guide to the Trifork server Figure 2.4. Deploying an application on the Trifork Enterprise Application Server bin]$trifork archive deploy default INSTALLATION_DIRECTORY/samples/simpleweb/simpleweb.war The server will ask for a username/password. Use administrator/trifork for this. The deployment command has a number of options. Issue the command trifork archive deploy -man for a detailed description of these Accessing the deployed application You can access the application by going to the following URL: Simple management To manage the Trifork Enterprise Application Server you should use the Trifork Management client. You start this by going to the INSTALLATION_DIRECTORY/domain/default/bin directory, and issuing the following command: Figure 2.5. Starting the Trifork Management client [devel@trifork bin]$trifork management client Username and password are administrator/trifork Configuring data sources Most J2EE applications need access to one or more data sources, e.g., an Oracle database. The Trifork Enterprise Application Server bundles JDBC drivers from DataDirect for Oracle, DB2, SyBase and SQL Server. Four data sources have been pre-created for these drivers. You can find these by clicking on Servers -> default -> Resources -> JDBC ->JdbcDataSources in the tree view. To use one of these in your J2EE application, you need to do two things: Adjust the data source to your database configuration: To do this, select the data source you want to use and right click on it. Select "Inspect" from the popup menu. An Inspector window pops up to the right of the tree view. In this window, change the username, password and URL/properties to reflect that of your database installation. Click the "apply" button to apply your changes Create a JDBC pool: To do this right-click on the JdbcPoolDataSource and select "Create JDBC Pool" from the popup menu. In the window which pops up to the right of the tree view, type a name and a JNDI name for the pool, and from the combobox, select the data source which you have just configured. Click the "create" button to create the JDBC pool You can now use the JDBC pool from your application by looking up its JNDI name HTTP endpoints By default the server is using ports 8080 and 8443 for http and https respectively. If you need to change this, select Servers -> default -> Resources -> HTTP -> Endpoints in the tree view. Right-click on "DEFAULT_ENDPOINT" and select "Inspect" in the popup menu. In the "Inspect" window which pops up to the right of the tree view, fill in the new ports for http and https, and click the "apply" button to apply your changes. Note 6

17 Chapter 2. The 20 minutes guide to the Trifork server On a Linux/Solaris system you cannot start a service on a port below 1024 unless you are root. 7

18 Part III. Overview of the Trifork platform The Trifork Enterprise Application Server enables you to develop, deploy, and run enterprise applications based on the J2EE component standard. The Trifork Enterprise Application Server provides a high-performance implementation of the complete J2EE standard. The server is certified according to the rules of the J2EE Compatibility Test Suite v In this guide we introduce the Trifork platform. The information in the following chapters is used throughout the documentation set. This guide contains: Introduction to the J2EE platform Trifork Enterprise Application Server Platform The Architecture of the Trifork Enterprise Application Server The "Introduction to the J2EE platform" chapter can safely be skipped by experienced J2EE programmers, but the "Trifork Enterprise Application Server Platform" chapter is fundamental for understanding the rest of this documentation. The chapter "The Architecture of the Trifork Enterprise Application Server" gives a high level introduction to how the Trifork Enterprise Application Server is implemented.

19 Chapter 3. Introduction to the J2EE platform This chapter gives a high level overview of the J2EE platform. Experienced J2EE programmers can safely skip this chapter J2EE Platform Overview Java 2 TM Enterprise Edition is a framework for building large scale information systems. Building on this platform, developers can construct interactive web sites, manufacturing systems, administrative systems, etc. There are several reasons why J2EE is becoming the platform of choice It is a very comprehensive framework for constructing large scale information systems. The various elements of the J2EE platform are consistently integrated, making it easy to extend and combine existing J2EE based systems. The J2EE platform is defined as an open standard, and compatibility with the J2EE standard can be established. What compatibility means is that the J2EE platform has been passed under the scrunity of the more than fifteen thousand tests that make up the J2EE 1.3 Compatibility Test Suite (The J2EE 1.2 CTS encompasses five thousand tests). You can recognize such products by the Java Compatible Enterprise Edition logo. The different architectural elements of the J2EE platform are depicted in Figure 3.1 Figure 3.1. J2EE platform architecture The J2EE platform consists of three types of artifacts: 9

20 Chapter 3. Introduction to the J2EE platform Component types: JSP, Servlet and EJB Containers: Client Application Container, Web Container and EJB container Services: JMS, JTA, JavaMail, etc. The following sections describe the different component types and the core services Component Types The J2EE application model is based on a set of component models and a set of common services used by these component models. As a developer, you create J2EE applications by developing Java classes conforming to these component models Enterprise Java Beans (EJB) An EJB is a server-side component that encapsulates the business logic of an application Entity beans Entity beans represent persistent domain entities, e.g. orders and customers. The state of an entity bean is typically stored in a DBMS. As a developer you must choose between the following types of entity beans: Bean managed persistence: With bean managed persistence, the developer must insert code to manage the persistence of the EJB. This code will typically use the JDBC API to talk to the DBMS. Container managed persistence: With container managed persistence, it is the responsibility of the EJB container to manage the persistence of the component. Instead of writing JDBC code, the developer merely defines an abstract mapping to the RDBMS which the EJB container realizes Session beans A session bean is a transient EJB, serving a single client. Developers use session beans to implement the application's business logic. Hence, session beans tend to implement procedural logic. Session beans are not persistent by nature. It is, however, possible to operate on persistent data (using JDBC) from within a session bean method. Session beans come in two shapes: Stateful session beans: A stateful session bean keeps client specific state between method invocations. The state is stored in the bean's instance variables. Stateful session beans are often used to realize a business process, such as assembling an order in an Internet based shop. As the customer chooses items to buy, the ShoppingCart EJB records the items in a collection. When the customer finalizes the order, the session bean uses entity beans to complete the order and store the order data in the database. Stateless session beans: A stateless session bean keeps no client specific state between method invocations. This allows the EJB container to service a large number of clients using a relatively small set of actual EJB instances. Hence, stateless session beans tend to scale better than stateful session beans Servlets A servlet is a Java object capable of responding to network requests. In general, servlets can be accessed via all request-response based protocols. In J2EE settings most servlets are invoked through the HTTP protocol. The work of the servlet typically consist of: Extracting input data from the request - typically data posted from an HTML form Given the input, executing business logic, typically by delegating the work to dedicated EJBs 10

21 Chapter 3. Introduction to the J2EE platform Based on the result from the EJBs, the servlet generates HTML based output presenting the result to the end user Java Server Pages (JSP) At runtime a JSP is a servlet. The difference is in the language you use for creating the JSP/Servlet. A JSP is declared in an extended version of HTML. Hence, JSP is convenient for Web designers J2EE Containers The J2EE containers provide deployment, management, and execution support for application components. One of the features of the J2EE platform is its support for a declarative programming style. Many component lowlevel details, e.g. persistence, security and multi-threading issues, can be declaratively specified in a deployment descriptor. This allow programmers to concentrate on business logic without worrying about low-level middleware details. It is the responsibility of the J2EE containers to provide an execution environment for the component fulfilling the requirements declared in the deployment descriptor Component Services The component services provide component developers with fundamental services, such as database access, enterprise naming systems access, etc Network Communication Technologies The J2EE platform allows clients to connect to the server using standard networking protocols over TCP/IP HTTP The HyperText Transfer Protocol. Used by web browsers to access resources at the web Server HTTPS HyperText Transfer Protocol over Secure Socket Layer (SSL). Used by web browsers to access resources at the web server in a secure way RMI Remote Method Invocation, the standard Java facility for distributing objects between different Java Virtual Machines RMI/IIOP An implementations of RMI, using the Internet Inter-ORB Protocol (IIOP). This allows programs written in such languages as C++ and Visual Basic to connect to Java objects distributed by RMI JDBC The JDBC API is Java's way of accessing any tabular data source, typically a relational database JNDI JNDI is an API that provides naming and directory functionality to applications written in Java. JNDI is defined independent of any specific naming or directory service implementation. Different naming and directory service providers can be plugged in seamlessly behind this common API. This allows Java applications to take advantage of information in a variety of existing naming and directory services, such as LDAP, NDS, DNS, and NIS JTA Java Transaction API (JTA) is a set of standard Java interfaces that allow client or server applications to initiate 11

22 Chapter 3. Introduction to the J2EE platform distributed transactions. JTA is a high-level transaction API, designed to be implemented using existing technology, e.g., CORBA OTS JavaMail The JavaMail API offers a standard API to communicate with standard Internet mail providers. 12

23 Chapter 4. Trifork Enterprise Application Server Platform This chapter describes the concepts underlying the Trifork Server, domains and the tools taht allow you to manage Trifork Server instances 4.1. Concepts A Trifork Enterprise Application Server installation consists of the following concepts Node - A node is a computer running one or more servers Server Instance - A server instance is a Java VM running an instance of the Trifork Enterprise Application Server System Container - A system container is a Trifork specific container containing J2EE containers Domain - A domain is a collection of servers managed together The concepts are explained in greater detail below Node A node can generally be thought of as a single computer. A node can host multiple Trifork servers. The servers hosted by a node, do not have to belong to the same domain (domains are explained later in Section 4.1.3). In large installations it is often useful to be able of control which servers are installed and running on which nodes. For this purpose the enterprise edition comes with a Node Manager program. This program makes it possible to perform management functionality on the node such as installing, starting and stopping server instances. Each node only needs to have a single instance of the Node Manager program running System Container On the Trifork Enterprise Application Server, deployed J2EE archives are at runtime hosted by a System Container. Each System Container contains an EJB Container and a Web container. The EJB and Web containers host the Web and EJB modules contained in the archives, respectively. Each server can have multiple System Containers, each hosting a number of applications. An archive's requirement to the server is described in a Trifork specific deployment descriptor. This file is always called trifork-app-conf.xml. The trifork specific deployment descriptor allows you to specify requirements which cannot be expressed in the standard J2EE deployment descriptors, e.g. virtual host names and port numbers for web applications. On the Trifork Enterprise Application Server only one trifork-app-conf.xml may exist per archive. Where the file is placed depends on the type of archive: META-INF for.ear,.jar and.rar archives WEB-INF for.war archives The Trifork specific deployment descriptor allows you to override settings in the J2EE specific deployment descriptors. This is very useful when you need to modify settings in a 3rd party module contained in your archive. Instead of unpacking the 3rd party module, modifying the modules deployment descriptor and repacking the module, you simple specify the setting in the Trifork specific deployment descriptor. This also ensures that you don't lose your customized settings when you obtain an updated version of the 3rd party developed module. System Containers have separate class loaders and can be independently configured and rebooted on the fly. For a server system hosting multiple J2EE applications this means that while one system requires maintenance or 13

24 Chapter 4. Trifork Enterprise Application Server Platform updating, other systems can continue undisturbed Domain A domain is a collection of servers that can be managed together. One of the servers in a domain is acting as a Domain Manager. The Domain Manager is a regular server with added management responsibilities and therefore acts as the access point for all management operations. The Trifork Enterprise Application Server management solution is based on (and compliant with) the J2EE Management Specification. Note The J2EE Management Specification will be a required component of the J2EE 1.4 platform. You can read more about the J2EE Management Specifiction at the J2EE tools site [ Trifork Enterprise Application Server is the only J2EE 1.3 certified application server to implement the J2EE Management Specification. The J2EE Management Specification defines a management information model for the J2EE platform, the J2EE Management Model. The root element of this model is the domain. In the context of a domain the model defines a set of types describing a J2EE server, its resources, and its deployed applications (Examples of types in the management information model include J2EEServer, JDBCDriver, J2EEApplication, EJB, and Servlet). The management model can be accessed through a server resident EJB component, known as the J2EE Management EJB Component (MEJB). The MEJB provides interoperable remote access to the model from any standard J2EE application. The domain and MEJB concepts are depicted in Figure 4.1 Figure 4.1. Domain 14

25 Chapter 4. Trifork Enterprise Application Server Platform 4.2. Domain Types The Trifork Enterprise Application Server has two types of domains: "Single Server Domain" and "Domain with multiple servers" Single Server Domain A single server domain contains a single server. The server acts as the Domain Manager and as a normal server. This type of domain is typically used for development and small production environments. If not specified otherwise a domain will be create as a single server domain Domain with multiple servers This type of domain consists of multiple servers and is often used in larger production environments. The Domain Manager Server is not used to host applications but only hosts management operations. The other servers in the domain host the applications Environments that need a higher degree of scalability and availability may configure multiple servers into a cluster. This allows the Trifork Enterprise Application Server to support fail-over and load balancing How to create a domain A new domain can be created by executing the createdomain script. The script can be found in the "server/ bin" directory of your Trifork Enterprise Application Server installation. Type createdomain -h for an explanation of arguments and options for the command Ways to manage servers Servers can be managed by using different types of management tools. The Trifork Enterprise Application Server provides the following tools: Trifork Management Client - The Management Client application provides a rich GUI for managing a Trifork Server Domain. Trifork command line tools - A set of tools for managing servers in a domain from the command line. Trifork Ant tasks - A set of Apache Ant tasks for invoking management operations. The Ant tasks resemble the Trifork command line tools. These different kinds of tools are all implemented by calling the MEJB on the Domain Manager Server. The different tools are described below Trifork Management Client The Trifork Management Client is the default management program for the Trifork Enterprise Application Server. It is implemented as a J2EE application client, and provides a rich Swing based GUI for managing a Trifork Server Domain. A typical screenshot is depicted below. 15

26 Chapter 4. Trifork Enterprise Application Server Platform The GUI consists of a tree view showing the J2EE Management Information Model. The root element is the Domain. To the right of the tree view is the desktop area. Various tools can be activated in the desktop area. The screenshot depicts the "Inspector Manager" and the "Server Monitor" tools. The "Inspector Manager" shows information about the selected element in the tree view. The "Server Monitor" monitors the health of a server instance. The Management Client application also allows you to create and alter different types of server resources, e.g. JDBC data sources, JMS connection factories, thread pools, HTTP port settings, etc. See Chapter 11 for a detailed description of the capabilities of the management client Trifork Command Line Tools The Trifork command line tools allow you to perform various management tasks directly from the command prompt. These include: Deploy applications to system containers Invoke J2EE client applications 16

27 Chapter 4. Trifork Enterprise Application Server Platform Create and modify server resources, such as system containers, JDBC data sources, JMS connection factories, and HTTP endpoints The command line tools are implemented by the trifork script located in the DOMAINDIR/bin directory. In Chapter 26 you can find a complete reference of the functionality of this tool Trifork Ant Tasks Trifork Ant tasks are a Trifork specific extension to the popular Ant [ build tool. This extension allows you to invoke the same set of commands, as provided by the Trifork command line tools, from within Ant. The Ant tasks can be used to create complete build and configuration scripts for J2EE development projects. Such a script could e.g. compile all java files, assemble them into J2EE archives, configure a Trifork Server instance with system containers, JDBC data sources, JMS connection factories, and finally deploy the archives to the configured server instance. Chapter 27 contains a detailed description of the Trifork Ant Tasks Domain Configuration Data All configuration data for the servers in a domain is stored in a configuration repository. The format of this repository is implementation specific, since Trifork supports multiple repository backends (e.g. flat files, LDAP, RDBMS...). If you need to access the preferences in a textual manner, e.g., for backup or duplication, the Trifork Enterprise Application Server provides support for exporting and importing the preferences to/from XML files. The format of the XML files is the same as the one used by the export/import mechanism of the J2SE 1.4 preferences library [ Use the trifork domain export (see Section ) and trifork domain import (see Section ) commands to export and import the preferences. 17

28 Chapter 5. Architecture and features of the Trifork Enterprise Application Server 5.1. Main Architectural Patterns The two main architectural patterns chosen for the Trifork Enterprise Application Server are Microkernel and Reflection. These patterns are described in detail in Pattern-orientented Software Architecture: A System of Patterns by Frank Buschmann, Regine Meunier, Hans Rohnert, Peter Sommerlad, and Michael Stal. The book defines the two patterns as follows: The Microkernel architectural pattern applies to software systems that must be able to adapt to changing system requirements. It separates a minimal functional core from the extended functionality and customer specific parts. The microkernel also serves as a socket for plugging in these extensions and coordinating their collaboration. The Reflection architectural pattern provides a mechanism for changing the structure and behavior of software systems dynamically. It supports the modification of fundamental aspects, such as type structures and function call mechanisms. In this pattern, an application is split in two parts. A meta level provides information about selected system properties and makes the software self-aware. A base level includes the application logic. Its implementation builds on the meta level. Changes to information kept in the meta level affect subsequent baselevel behavior Microkernel Architecture In the Trifork Enterprise Application Server, we use the Microkernel pattern as a mechanism to structure the server. We use kernel modules to realize the individual containers and middleware API implementations. To the microkernel pattern, we have added the notion of hierarchical nesting of kernel modules, i.e., a module can contain other modules. At runtime, the Trifork Enterprise Application Server consists of a module hierarchy as depicted in Figure 5.1. Figure 5.1. Microkernel modules ORB Module The J2EE platform incorporates the Object Management Group's (OMG) protocols which allow access to distributed objects using the OMG's Common Object Request Broker Architecture (CORBA). The ORB module manages the CORBA ORB used by the Trifork Enterprise Application Server. Other modules use the services provided by the ORB module to create remote access to EJBs managed by the EJB Container (see Section ) and to provide secure remote access to JMX based management agents (see Section 5.2.8). 18

29 Chapter 5. Architecture and features of the Trifork Enterprise Application Server The default implementation uses a high performance ORB developed by Trifork Technologies. This ORB has been carefully designed to fit seamlessly into the server. Some of the features include: Optimized for J2EE invocation: The implementation is focused on providing speed and scalability to EJB based objects, and not (necessarily) to other types of CORBA objects Optimized for the Trifork Enterprise Application Server: The ORB has been implemented using the same principles and APIs that govern the Trifork Enterprise Application Server. For instance, the ORB uses the Thread Pool (see Section 5.2.9) provided by the application server. This greatly reduces the number of allocated threads needed to support a heavy load on the application server. The ORB implements the CORBA Portable Object Adapter (POA) API. The POA takes care of object activation and deactivation on the method invocation boundary. In large scale EJB based systems the EJB container must be able to serve millions of EJB instances. Because the EJB container must operate in limited memory, the POA becomes fundamental to achieving this in an efficient manner. The ORB provides implementations of Objects-by-value and RMI over the IIOP protocol. Furthermore the implementations support passing security and transaction contexts over the IIOP wire (as mandated by the CSIv2 CORBA Secure Interoperability specification and the CORBA OTS specification). This allows J2EE applications to connect to other J2EE applications across multiple J2EE products, whether from different Product Providers or from the same Provider, and multiple J2EE platforms Naming Module J2EE application clients, enterprise beans, and web components are required to have access to a JNDI naming environment. A component uses the naming environment to look up resources (e.g. JDBC connections and references to enterprise beans) during its execution. In the Trifork Enterprise Application Server, it is the responsibility of the Naming Module to provide this functionality. The Naming Module consists of: Generic Naming System (GNS): The GNS provides a generic implementation of the features provided by most naming systems. The GNS does not conform to any Naming Service standards. Instead, compatibility with existing standards is provided by Protocol Adapters Protocol Adapter: The role of a Protocol Adapter is to provide an implementation of a Naming Service standard (e.g. JNDI). The Protocol Adapter implements the naming service standard by using the services provided by the GNS The current version of Trifork Enterprise Application Server ships with Protocol Adapters implementing JNDI and COS Naming (with support for INS), both required by the J2EE v. 1.3 specification Transaction Manager Module The Java Transaction API consists of three elements: javax.jta.usertransaction: a high-level application transaction demarcation interface javax.transaction.transactionmanager: a high-level transaction manager interface intended for application servers javax.transaction.xa.xaresource: a mapping of the X/Open XA protocol intended for transactional resource managers Trifork Technologies' implementation of JTA is realized on top of an implementation of the OMG Object Transaction Service (OTS). 19

30 Chapter 5. Architecture and features of the Trifork Enterprise Application Server Trifork Technologies' Transaction Manager supports the use of JTA's UserTransaction in: EJBs with bean managed transactions Web applications (Servlets and JSPs) J2EE client applications Note Transaction support from web and client applications are not required by the J2EE specification, but supported in the Trifork Enterprise Application Server as a value added feature! Many applications do not have requirements for distributed transactions (two-phase commit). In such cases, the transaction manager will optimize the commit from a two-phase to a one-phase commit Security Module The Security Module provides facilities for user authentication and authorization. Authorization and authentication are performed in the client container, in the web container and in the EJB container. In all three areas the Trifork Enterprise Application Server is based on JAAS (Java Authentication and Authorization Service) whereas the J2EE specification only demands this for the client container. This opens up the possibility of pluggable server side security technology. The Security Module includes support for both a simple file based security realm with the ability to manage users and user groups, and the ability to use LDAP. Authorization between client container and ejb container is based on CSIv2. This is not a J2EE specification demand; however, CSIv2 is mandated for interoperating with other J2EE implementations Repository Module The Repository Module manages the storage where deployed J2EE applications are stored JDBC Pool Module The JDBC Pool Module is constructed to support pooling of database connections, and multiplexing of several database sessions on top of a single physical database connection by utilizing the XA protocol. This results in a significant performance advantage. When a J2EE component needs a JDBC connection, it gets it from the pool by looking up a data source object using JNDI. The data source object is implemented by Trifork in order to work in concert with the pool module. After using the connection, the component calls the Connection.close() method. The close() method returns the connection to the pool for use by another component. The JDBC Pool Module is capable of managing different pools, i.e., connections to different databases. The pools are configured using the management client (see Section 11.3 for detail on how to do this) Log Module The Log Module provides an API for performing logging inside the application server. Log entries belong to a context and the severity is expressed by a log level. Log contexts are structured in a hierarchy and can be turn on/off at runtime. The severity (level) is one of: error, warning or debug. The current implementation is based on the Log4j package [ from the Apache Software Foundation [ Management Module An important aspect of running an application server in production settings is management. The Management 20

31 Chapter 5. Architecture and features of the Trifork Enterprise Application Server Module provides the core management infrastructure, allowing other modules in the server to register JMX based management agents. The Management module also allows management (client) applications to connect to the server and obtain management information. The Management module conforms to the J2EE Management specification described in Section Thread Pool Module The Thread Pool Module manages most of the threads used by the application server. Since threads are rather heavy-weight entities it is a performance optimization to recycle threads to the pool. All request handling modules (e.g the ORB, Web Container and JMS) reuse threads from the same thread pool System Manager Module It is the responsibility of the System Manager Module to provide means to create, start, stop, and destroy System Containers System Container Module The System Container Module was described in Section EJB Container Module EJBs are hosted by instances of the EJB Container Module. It is the responsibility of the EJB Container Module to provide an execution environment for EJB as dictated by the deployment descriptor contained in the EJB's jar file Computational Reflection The traditional way for an EJB container to realize the execution environment for an EJB is to generate two classes implementing the EJB's Home and Remote interface. When generating the methods contained in the EJB's interfaces, the container generates code realizing the declarative requirements specified in the EJB's deployment descriptor. It is not uncommon that each generated method contain lines of Java source code. At runtime, each EJB instance needs several support objects; an instance of the SessionContext/EntityContext, an instance of the generated class implementing the Remote interface, instances of Stub/Skeleton classes providing network access to the EJB, an instance of the EJBMetaData type, etc. The design of the Trifork Enterprise Application Server strives to reduce the amount of resources needed to support J2EE components. By reducing the amount of objects (memory) necessary to host a J2EE component instance, it is possible to host more instances in the same amount of memory. By using advanced techniques, such as Computational Reflection, the Trifork Enterprise Application Server is able to run Sun Microsystems Java Pet Store demo application in just 6MB of ram (where other servers use 64MB or more!). Computational reflection is based on a model where each object has its own meta-object that represents otherwise implicit information: its structure and its way of handling method invocation. Research prototypes of programming languages have shown that computational reflection allows for the implementation of new features not initially in the system. In the Trifork EJB Container, all EJB components are reified, i.e., transformed into something which can be manipulated at the meta-level. Each EJB component type is described, at the meta-level, by a meta-class. The meta-class contains all structural information known about the component type: name, remote interface, home interface, implementation class, security and transaction settings, etc. At runtime, each instance is assigned a meta-object. The meta-object is responsible for handling method invocation for the EJB instance. The meta-object uses the information stored in the EJB's meta-class to execute the method invocation as specified by the deployment descriptor and the J2EE specification. Some of the advantages obtained using computational reflection instead of code generation are: Reduced memory footprint: A careful design of the meta-object layer reduces many of the support objects needed by a code-generation architecture Easy implementation of new features: Since meta-objects handle method invocation on EJB instances, it's 21

32 Chapter 5. Architecture and features of the Trifork Enterprise Application Server easy to mix-in new behavior as part of the normal message handling semantics. For instance, the EJB 2.0 notion of local invocation between EJBs was implemented in a single day! Performance improvement: Due to meta-objects, our implementation does not contain code generated implementations of the EJB's remote interface (containing lines pr. method). This significantly reduces the total amount of code in the running system, giving advanced virtual machines, such as HotSpot, a much easier job optimizing the running server as a whole Runtime Code Generation EJBs managed by the EJB Container are distributed using the RMI/IIOP protocol. This allows applications written in such languages as Java, C++ and Visual Basic to use the functionality provided by the EJBs Where most application servers generate large amounts of Java code as part of EJB deployment for RMI/IIOP stubs the Trifork Enterprise Application Server builds minimal reflection-driven stubs on the fly by constructing Java byte code directly in-memory. This provides not only for significantly reduced deployment turnaround time, but most importantly it significantly reduces the total amount of code, making it a lot easier for HotSpot to optimize the system Web Container Module The Web Container Module provides complete Web server functionality. The module can be accessed using either HTTP or HTTPS. The Web Container module can host static content, Servlets and JSPs (with taglibraries). The Web Container supports virtual hosting, which allows a single server to host multiple Web sites with different host names. 22

33 Part IV. Installation This guide contains detailed information on how to install the Trifork Enterprise Application Server and get it running.

34 Chapter 6. Preparing the installation This chapter contains information which can be handy before you start an installation of the Trifork Enterprise Application Server. First we look into how to download the Trifork Enterprise Application Server, and which version to choose. Next, a brief comment on the 30 trial license key is given, and finally how to choose the installation directory and free space issues are discussed Downloading the Trifork Enterprise Application Server Since you are reading this user guide you have probably already downloaded the Trifork Enterprise Application Server. In this case, skip this section and jump to Section 6.3. If you have not downloaded the Trifork Enterprise Application Server, simply go to: the Trifork Enterprise Application Server download page [ On this page you will be asked to fill out a registration form. Having done this, you will be redirected to a page from which you can download the Trifork Enterprise Application Server. You have several choices for which version to download. First of all you should decide on a platform: Windows: suitable for Windows NT, 2000, XP and 2003 Server systems. UNIX: suitable for SPARC Solaris and i386 Linux (RedHat, SuSE etc.) system. If you are using Windows you have the choice of downloading the Trifork Enterprise Application Server with or without a Java Development Kit (JDK): With JDK: suitable if this is your first download of the Trifork Enterprise Application Server and you do not already has a JDK installed on your system. Without JDK: suitable if you have previously downloaded the Trifork Enterprise Application Server and just want to upgrade the server and not the JDK. It is also suitable if you are an experienced Java developer who already has a JDK installed on your system. In this case make sure that your JDK is version or equivalent (JDK-1.3 will not work!) Handling the 30 day trial license key When you have filled out the registration form, a confirmation will be sent to you. Attached to this will be your 30 day trial license key. Without this key, the Trifork Enterprise Application Server will not start, so make sure not to delete the . Furthermore, 30 days from the day you filled in the registration form, the key will expire. Installation of the 30 day license key is explained in Section Preparing a directory for installation Having downloaded the Trifork Enterprise Application Server you have to decide upon a directory to install the server into. At the moment the path to the installation directory must not contain any spaces, so a suggestion for an installation directory could be c:\trifork if you are using Windows, and /home/your_username/trifork if you are using Solaris or Linux. During the installation, the installer will ask for an installation directory and create it if it does not exist. If you are using Linux, you must first unpack the downloaded archive to a temporary directory, e.g., /tmp. This will create a directory called trifork-3.2.x containing the installer. Before you install, you must also make sure that you have sufficient space left on the device you are installing 24

35 Chapter 6. Preparing the installation the Trifork Enterprise Application Server into. The amount of space taken up by a Trifork Enterprise Application Server installation depends upon which version you have downloaded (e.g., with or without the JDK). Also consider that the application you are going to deploy on the Trifork Enterprise Application Server will take up space, as well as log files etc. 25

36 Chapter 7. Installing on Windows This chapter explains how to install the Trifork Enterprise Application Server on Windows 2000 and Windows NT systems Normal installation Installing the Trifork Enterprise Application Server on a Windows system is very simple. Just double-click the downloaded installation archive and follow the directions given by the installation wizard. Having done this, you can start having fun with the Trifork Enterprise Application Server. If you prefer a more in-depth explanation of the steps involved in the installation, follow the step-by-step guide provided in the following section Step-by-step guide Startup When you double click the downloaded installation archive, you will be greeted with the following window. Press the Next button to proceed Startup Read the license carefully, and press the Yes button if you accept. 26

37 Chapter 7. Installing on Windows Selecting the installation directory The first thing you need to do is select a directory where the Trifork Enterprise Application Server should be installed. As mentioned in Section 6.3 the path to the installation directory must not contain any spaces. If you are in doubt, just select the default directory. 27

38 Chapter 7. Installing on Windows Selecting Components Having selected the installation directory, you must decide which components to install. We recommend that you install all the components, but to save space you can leave out the Java Development Kit if you already have this installed. 28

39 Chapter 7. Installing on Windows Selecting the start menu folder The Trifork Enterprise Application Server will install a start menu folder containing shortcuts for starting the server etc. If you want to use another name than the default one, or do not want the start menu folder to be installed at all, change this in the next window. 29

40 Chapter 7. Installing on Windows Creating the desktop icon Besides the start menu folder, you also have the option of installing a shortcut to the Trifork Enterprise Application Server on your desktop. 30

41 Chapter 7. Installing on Windows Verifying installation information Before you start the actual installation take a moment to verify that the specified information is correct. If it is, press the Next button. Otherwise, press the Back button to go one or more steps back and change the installation information. 31

42 Chapter 7. Installing on Windows Installing Now the actual installation starts. When the progress bar reaches 100% you are allowed to continue. 32

43 Chapter 7. Installing on Windows Exiting the installer The installation is now finished and you can start having fun with the Trifork Enterprise Application Server. 33

44 Chapter 7. Installing on Windows 7.2. Installing Trifork Enterprise Application Server as a Windows Service If you are using Windows the installed Trifork Enterprise Application Server can be configured to run as a Windows Service. To do this you nee,d to go through the following steps: Inspect the JDK_ROOT key in the <INSTALLATION_DIR>\servers\bin\service.ini file (where IN<STALLATION_DIR> is the directory, where you chose to install the Trifork Enterprise Application Server). By default this is set to the bundled JDK, but if you chose not to install the JDK or you would like to use another JDK, you have to change this key. Note: The service might not work, if you specify a drive that has been assigned using the SUBST command! Now, from the same directory run the InstallTriforkService command. Following this you can start and stop the service by issuing the following two commands, respectively: net start TriforkServer net stop TriforkServer If you want to remove the Trifork Service, simply run the UninstallTriforkService command. The service is installed using the default server in the default domain. If you want to use another server in another domain you need to change some settings in the <INSTALLATION_DIR>\servers\bin\service.ini file: 34

45 Chapter 7. Installing on Windows Set TRIFORK_DOMAIN_NAME to your domain name. Set TRIFORK_SERVER_NAME to your server name. If your domain doesn't reside in the <INSTALLATION_DIR>\domains directory, set TRIFORK_DOMAIN_DIR to your domain directory. Change stdout, stderr and workingdir to something appropriate for your installation. Reinstall the service. 35

46 Chapter 8. Installing on Unix This chapter describes how to install the Trifork Enterprise Application Server on a Unix-line operating system. Note The Trifork Enterprise Application Server and this installation procedure have been tested on SPARC Solaris and Linux (RedHat 7.x, 8 and 9, and SuSE 7.x, 8.x). It will probably also work on other types of i386 Linux systems, but probably not on other types of UNIX operating systems. If you are using another type of UNIX operating system than Sparc Solaris or i386 Linux, and would like to use the Trifork Enterprise Application Server, please contact our Sales Department [mailto:sales@trifork.com]. We will then try to help you. To install the Trifork Enterprise Application Server on a Unix-like system, unpack the archive to a temporary directory, e.g. /tmp, and go to the directory resulting from this: [devel@trifork ~] cp trifork-3.2.x-unix.tar.gz /tmp [devel@trifork ~] cd /tmp [devel@trifork ~] gunzip trifork-3.2.x-unix.tar.gz [devel@trifork ~] tar -xvpf trifork-3.2.x-unix.tar [devel@trifork ~] cd trifork-3.2.x Now start the installation wizard by typing: [devel@trifork ~]./install And follow the directions given by it. When the installation wizard completes, you are ready to start having fun with the Trifork Enterprise Application Server. 36

47 Chapter 9. Starting the server for the first time Having installed the Trifork Enterprise Application Server, this chapter focuses on how you can quickly get started using the Trifork Enterprise Application Server. First, if you are using the trial version of the Trifork Enterprise Application Server a license key should be installed. How this is done is dealt with in Section 9.1. If you are not using a trial version you can just skip this section. Next we explain how you start and stop the server, plus how you verify that the server is indeed running. Finally, Section 9.6 provides information on how you can easily run the sample applications bundled with the Trifork Enterprise Application Server 9.1. Installing the license key When you download the trial version of the Trifork Enterprise Application Server you will need a license key in order for the Trifork Enterprise Application Server to start. Right after you have registered for a trial download at the Trifork website, an will be sent to you. With this mail, the license file will be attached as license.txt. To install this license key, simply take the license.txt file and move it to the INSTALLA<TION_DIR>/server/license directory Creating a new domain When you install the Trifork Enterprise Application Server a default domain containing a default server is provided for you. This is all you need to get started. Should you need to create a new domain simply use the createdomain command, which can be found in the <INSTALLATION_DIR>/server/bin directory. Using the createdomain command, a new domain is created from the command line by typing: createdomain <dir-to-create-domain-in> <domain-name> <server-name> 9.3. Starting and stopping the server Except for creating domains the Trifork Enterprise Application Server is controlled by the trifork command, which can be found in the <TRIFORK_DOMAIN_DIR>/bin directory. Using the trifork command, the server is started from the command line by typing: trifork server start As a further convenience two scripts for starting the server are provided in the / <TRIFORK_DOMAIN_DIR>bin directory: startdevelserver-default for starting the default server in development mode and startproductionserver-default for starting the default server in production mode. Se Section for more information on start modes. Corresponding to this, the Trifork Enterprise Application Server is stopped by the following command (in another console window): trifork server stop Or simply by pressing CTRL-C in the console window where you started the server. The trifork command has many more functionalities which are described in detail in Chapter Server start modes The Trifork Enterprise Application Server can be started in two different modes: development and production. 37

48 Chapter 9. Starting the server for the first time You use development mode to develop and test your applications. Once they are ready for a production environment, you deploy your applications on a server that is started in production mode. Development mode It is possible to make a permanent login on the server. This greatly simplifies the interaction with the server since the user doesn't have to provide username/password on each command. See Section 9.5 for more information on making a permanent login. The server checks for updated jsp-files that were deployed inplace and automatically recompiles these. Errors from the web-container are propagated to the browser, making it easy to pinpoint the cause of the error. Production mode It is not possible to make a permanent login on the server. This enhances security on the server, but requires the user to provide username/password on each command. The automatic jsp-recompile is disabled which enhances performance on the server. Errors from the web-container are not propagated to the browser. By default the Trifork Enterprise Application Server runs in production mode. To start a server in development mode, do one of the following: Using the Trifork Server Start command add the option -devel. Start the server using the script startdevelserver-<server-name> Starting the Trifork Enterprise Application Server from Windows If you are using Windows you have an alternative way of starting the Trifork Enterprise Application Server. When the installation of the Trifork Enterprise Application Server is complete, shortcuts to startdevelserver-default have been created on the desktop and in the Start menu. By selecting one of these, the Trifork Enterprise Application Server is started Verifying that the server is running When you start the Trifork Enterprise Application Server as described above, the server will output something like the following from the command line you started it from: C:\Trifork-3.2\domains\default\bin>trifork server start Trifork Server v3.2.0 Copyright (c) 2002 by Trifork A/S Domain name : default Server name : default Host name : myhost ( ) Booting domain image C:\Trifork-3.2\domains\default... Internal HSQL DB is running (version=1.7.1) Server running When you see the "Server running" line, the Trifork Enterprise Application Server is up and running. To further verify this, point your browser to the host on which you have started the Trifork Enterprise Application Server. The port should be If you have started the Trifork Enterprise Application Server on your local machine the following link should work: If the server is running correctly your browser will now show you a simple welcome page, containing informa38

49 Chapter 9. Starting the server for the first time tion on the server version, the current time, when the server was started and a link to the Trifork website Changing the administrator password When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. By default the administrator user acts as the administrator of the server, and is, e.g., used when you want to perform system commands such as deploying an application, stopping the server etc. It is recommended that you change the password for the administrator user. By default, the password is set to trifork. You can change this password (or the password for any user in the server for that matter) by issuing the following command: trifork realm updateuser administrator <your_new_password> The server needs to be running when you execute this command. If the server is not running in development mode, it will ask for a username and password to perform the action. Initially use administrator/trifork, subsequently use administrator/<your_new_password> Making a permanent login on the server Having changed the password for the administrator user, you are ready to start using the Trifork Enterprise Application Server. The tools used for tasks such as deploying an application, creating a user, stopping the server etc. will ask for username and password as required. In development situations this can become a hassle. As an alternative you can use the following command to make a permanent login on the server, thus eliminating the need for making a login each time you use the commands on a server started in development mode: c:\trifork-3.2\domains\default\bin>trifork auth login Please specify username to connect with [administrator]:administrator Please specify password to connect with:<your_administrator_password> Caution: by issuing the 'trifork auth login' command a file named '.triforklogin' will be created in your home directory. This file contains an encrypted version of the specified username and password. The server will subsequently use the username and password from this file when running in development mode. Please make sure that this file is kept private since, if distributed, it can be used as a management key to your server Deploying and running the example applications A number of simple example applications are provided with the Trifork Enterprise Application Server. In Part X three small examples of how to use EJBs and Servlets on the Trifork Enterprise Application Server as well as information on how to deploy them, are presented. Beside these, the Java Pet Store Sample Application is bundled with the Trifork Enterprise Application Server. In the following a brief description of this application will be given, as well as directions on how to run it. For more information on the application itself see Section The Java Pet Store Sample Application The Java Pet Store Sample Application is a full-fledged online store illustrating the Java 2 Platform Enterprise Edition Blueprints [ The version bundled with the Trifork Enterprise Application Server is based on Sun Microsystem's Java Pet Store application version which can be downloaded here [ In comparison with the version of the Java Pet Store Sample Application you can download above, the bundled version has been modified as follows: Trifork Enterprise Application Server specific deployment descriptors are included in the archives. A slight change to some SQL statements has been performed, in order to support the Hypersonic Database bundled with the Trifork Enterprise Application Server. 39

50 Chapter 9. Starting the server for the first time Running the Java Pet Store Sample Application The Java Pet Store Sample Application can be found in the <INSTALLATION_DIR>/samples/petstore directory. In this directory a build.xml Ant file for automatic deployment of the application can also be found. Bundled with the Trifork Enterprise Application Server is a samples domain, where the Pet Store Application has already been deployed. You simply have to start the samples server and Petstore is up and running: From the directory <INSTALLATION_DIR>/domains/samples/bin type the command: trifork server start Or select the Start Samples Server menuitem from the Trifork Enterprise Application Server start menu. When you have deployed the Java Pet Store Application you can access it using the following link View Petstore [ or by selecting View the Petstore Sample Application from the Trifork Enterprise Application Server start menu. 40

51 Part V. Configuring and managing the Trifork Enterprise Application Server This guide describeds how to configure and manage the Trifork Enterprise Application Server.

52 Chapter 10. Domains All configuration and management of the Trifork Enterprise Application Server is done in the context of a server in a specific domain. See Section for a detailed description of the role of the domain in the Trifork Enterprise Application Server platform. The rest of this chapter will focus on practical usage of the domain Creating a domain When you install the server, a standard domain is created. The domain is called default and can be found in the INSTALLATION_DIRECTORY/domains/default directory. If you have chosen to install the sample application an additional domain called samples can be found in the INSTALLATION_DIRECTORY/domains/samples directory. For most purposes you should be fine with these domains. However, in some situations it may be appropriate to create additional domains. If a domain already exists, you can create a new domain by going to the bin directory of the domain and issue the following command: trifork domain create See Section 26.6 for detailed information on the command. If you do not have an existing domain, you must issue the following command to create a domain: <INSTALLATION_DIRECTORY>/server/bin/createdomain The arguments to this command are the same as for the trifork domain create command Domain directory layout A domain is represented on the file system by a number of files and directories. In most cases you will not need to access these files and directories. However, in certain situations it is necessary to know the meaning of the files and directories. As a help in these situations, this section describes the directory layout of a domain. In the rest of the section we will assume that you are using the "default" domain which was created during installation. If you have created a new domain, simply substitute the domain and server name with the ones from your own domain. The domain named "default" is located in INSTALLATION_DIRECTORY/domains/default. In the domain directory you will find the following directories: bin lib logs config client-config servers applicationrepository preferences 42

53 Chapter 10. Domains The purposes of these directories are described in the following subsections bin The bin directory contains three types of scripts in both the Windows and Linux/Solaris versions: Scripts for setting the environment: This script is called setdomainenv. This script is used by the other scripts. Scripts for starting the server: The server can be started in both development and production mode (see Section for a detailed description of the two modes). The startdevelserver-default and startproductionserver-default scripts will start the server in development and production mode respectively. General command line command: The trifork script is the general command line script. With this script you can execute a number of management commands from the command line. See Chapter 26 for a detailed reference of the possibilities of the trifork script. The trifork script uses the setdomainenv script, so the trifork script is only applicable for issuing commands for servers residing in the domain in which the trifork script is placed lib The lib directory is an easy way to add JAR files to the server's classpath. Examples of JAR files you might want to add to the server's classpath could be JDBC drivers or libraries you want to use directly from your application. The lib directory contains a number of subdirectories, in which the JAR files must be placed: One directory for each server you have in the domain. These directories have the same name as the server (in the default domain there is only one server, therefore the lib directory contains a subdirectory named default). JAR files placed in these directories will be added to the classpaths of the individual servers. A directory called share. JAR files placed in this directory will be added to the classpaths of all servers in the domain. Note The JAR files are loaded when the server is started. If you place a JAR file in one of the lib subdirectories while the server is running, it won't be added to the servers classpath until the server is restarted logs As with the lib directory, the logs directory contains one subdirectory per server in the domain, i.e., the logs directory of the default domain contains a single subdirectory called "default". In these directories logs for each server in the domain are stored. Depending on your log configuration (see Section for detailed information on how to configure logging), a number of log files are present: server.log: when standard log configuration is used, the server logs to this file server_debug.log: when debug is configured for one or more logging categories, these log messages are placed in this file user.log: log messages made with ServletContex.log() are stored in this file access.log: the web container can be configured to create an access log for HTTP access. These log messages are stored in this file config The config directory contains subdirectories structured in the same manner as the logs directory. Each of the subdirectories contains two configuration files: 43

54 Chapter 10. Domains log4j-server.log: Use this file to configure logging for the server. The file is a normal XML configuration file for the Log4J system [ Detailed information on how to configure logging can be found in Section server.properties: In this file you can place properties that should be available to your application. When the server starts, this file is read, and the properties in it added as system properties client-config The client-config directory contains configuration files used when executing J2EE application clients inside the application container (see Section 21.5 for details on the client container). The directory contains two configuration files: log4j-client.xml: Use this file to configure logging for the client container. The file is a normal XML configuration file for the Log4J system [ Detailed information on how to configure logging can be found in Section client.properties: In this file you can place properties you want to be available for your J2EE application client. When the client container starts the file is read, and the properties in it added as system properties servers The servers directory contains a subdirectory for each server in the domain. Each subdirectory in turn contains four subdirectories: config: This directory is used for storing SSL certificates as well as the datafile for the default realm. db: This directory is used by the embedded database to store data. public: This directory contains the "public" application. This is a inplaced-deployed web application which can be used to test simple JSP and HTML pages. You simple copy your JSP or HTML file to this directory and the file will immediately be available on the following URL: repo: This directory is used internally by the system container for caching purposes applicationrepository and preferences These two directories are used internally by the server to store deployed applications and preferences respectively. You should never access these directories directly, but instead use the trifork archive deploy, trifork archive undeploy and trifork management client commands. 44

55 Chapter 11. Configuration The Trifork Enterprise Application Server is configured using the Trifork Management Client The trifork management client The Trifork Management client is a J2EE application client that enables you to perform two main tasks: Configure a running server - which is described in this chapter Monitor a running server - which is described in Chapter 15 To start the Trifork Management client, go to the INSTALLATION_DIRECTORY/domains/default/bin, and issue the following command: trifork management client If you are using Windows you can also start it from its icon in the Trifork program group in the Start menu. When the Management client starts it will ask you to log in with a username and a password. Use administrator/trifork for this. After you have successfully logged in, you are presented with the main window of the Management client, see Figure Figure Initial window when the Management client is started The window has two main parts: 45

56 Chapter 11. Configuration The tree view - this is the left pane in the window. The tree view presents an overview of the servers in the domain, as well as the content of each server. When working with the Management client you navigate the servers with the tree view, and right-click on a node to apply actions to this node. The desktop view - this is the right pane in the window. The desktop view is used for opening windows when you apply actions to the nodes in the tree view. As an example, a window will pop up in the desktop view if you select the action "Inspect" on a node in the tree view. For each server in the tree view four main nodes exists (see Figure 11.2): DeployedObjects: An overview of the objects currently deployed on the server. You can browse the tree view to get a detailed view of which objects are deployed. JavaVMs: This node provides information on which JavaVM is running the server. Resources: The Resources node contains information on the different resources running in the server, e.g. JDBC Datasources and pools, JMS Queues and Topic Factories. The configuration of each of these resources will be dealt with in the following sections. SystemContainers: A list of the system containers in the server. For each system container you can browse which components have been deployed into it. Figure The tree view In the tree view you can right-click on the nodes and from the popup menu select an action to perform on the selected node. There are two types of actions which can be performed: 46

57 Chapter 11. Configuration Node specific actions: These actions are placed in the upper part of the popup menu, and typically includes actions to create and remove resources General actions: Inspect: This will bring up an Inspector window for this specific node or leaf. If you select Inspect on another node, another Inspector window will be opened for this node/leaf Open in Inspector Manager: When selecting this action a general inspector window called the Inspector Manager will be opened. This window basically shows the same information as the Inspect windows, but when you select another node in the tree view, the Inspector Manager will show the data for this node instead. Thus, only one Inspector Manager can be opened In Figure 11.3 an example of the actions popup menu is shown. Figure Example of the actions popup menu HTTP 47

58 Chapter 11. Configuration HTTP configuration in the Trifork Enterprise Application Server is done via HTTP Endpoints. An HTTP Endpoint is a configuration unit containing information about HTTP(S) port(s), virtual host, connection backlog etc. When a web application is deployed into the server, the web application is associated with an HTTP Endpoint. This is done in the trifork specific deployment descriptor (trifork-app-conf.xml) by using the <endpoint> tag. This means that if multiple web applications use the same HTTP Endpoint, you can change the HTTP configuration for all of these web applications (even across system containers) just by reconfiguring the HTTP Endpoint. By default the Trifork Enterprise Application Server comes with two preconfigured endpoints: DEFAULT_ENDPOINT: This endpoint is used by all web applications which do not specify an <endpoint> tag in the trifork specific deployment descriptor. PROFILE_ENDPOINT: This endpoint is used by the Semantic Profiler application bundled with the server. See Part IX for information on the Semantic Profiler Configuring an existing endpoint To configure the HTTP Endpoints, start the Management client and use the tree view to browse to the HTTP Endpoints in the HTTP resource. Click on the DEFAULT_ENDPOINT node In the Inspector Manager window, in the desktop view, you can now fill in/change the values for the HTTP Endpoint. This is depicted in Figure Figure Changing the values for a HTTP Endpoint Each HTTP Endpoint supports three protocols: HTTP, HTTPS and AJP (AJP is the protocol used to communicate with the apache plugin). Depending on how many of these protocols you have enabled, you can fill in a number of properties for the HTTP Endpoint. If you do not specify any value for a property the server will use 48

59 Chapter 11. Configuration its default value. The HTTP Endpoint supports the following properties: Virtual host: Specifies which virtual host the HTTP Endpoint binds to. Clients (i.e., web browsers) need to support HTTP 1.1 for this feature to work. Default host: If the clients only supports HTTP 1.0 you may need to specify a default host name to be put into the headers, in order to make redirection work properly. Http port: Specifies the port on which the Trifork Enterprise Application Server accepts HTTP requests. The default value is Http backlog: Specifies how many connect requests may be pending in the TCP/IP stack for HTTP at a given time. The default value is 500 Https port: Specifies the port on which the Trifork Enterprise Application Server accepts HTTPS requests. The default value is 8443 Https backlog: Specifies how many connect requests may be pending in the TCP/IP stack for HTTPS at a given time. The default value is 500 When you are finished configuring the HTTP Endpoint click the apply button to apply your changes Creating a new endpoint If you want to create a new HTTP Endpoint, select the HTTP Resource from the tree view. Right-click on it and from the popup menu select Create Http endpoint. A window will appear where you can fill in the data for the new HTTP Endpoint. This is illustrated in Figure Figure Create new HTTP Endpoint 49

60 Chapter 11. Configuration Data sources When you are configuring data sources for the Trifork Enterprise Application Server, three types of resources are involved: CMPTypeMappings: Defines the mapping between Java types and the types used by the individual database vendors JdbcDataSources: Defines which data to use (JDBC driver, host, user name, password, etc.) when connecting to a specific database JdbcPooledDataSources: Defines a pool for a specified JdbcDataSource In the following section the configuration of these three types of resources is described in detail CMP type mappings When storing the state of enterprise beans using CMP (Container Managed Persistence) from Java to a database, a type mapping between the Java type and the SQL type used in the database is performed. These mappings are defined in a CMPTypeMapping. The appropriate mapping may vary between DBMS products. For example, a java.lang.long could be mapped to the type BIGINT on a Microsoft SQL Server and NUMBER(19,0) on an Oracle database server. Consequently it is possible to define dataase specific mappings in the Trifork Enterprise Application Server. The Trifork Enterprise Application Server provides you with preconfigured CMPTypeMappings for the most common databases. You can view (and edit) these by browsing to the CMPTypeMappings node in the tree view of the Management client. This is shown in Figure 11.6 Figure CMP type mappings 50

61 Chapter 11. Configuration JDBC Data Sources Access to databases is configured by JDBC data sources. In order to configure a JDBC data source you need to provide: A JDBC driver for the specific database Configuration data for connecting to the database JDBC Drivers A JDBC driver provides the ability to communicate with a particular database system. JDBC drivers exist for most well known database systems, and are often supplied with the database management system. Furthermore, JDBC Drivers from third part vendors are often available. A list of J2EE compliant JDBC drivers can be found at JavaSoft's website [ Trifork bundles the JDBC driver from DataDirect Technologies, Inc. The reason we have chosen to bundle the DataDirect driver is that they are one of the leading data connectivity vendors in the industry. The DataDirect Connect for JDBC drivers are rigorously tested using JavaSoft Certification Test Suite and the DataDirect Technologies JDBC Verification Suite, one of the most comprehensive JDBC testing facility in the industry. Our experience tells us that using the DataDirect Driver enables faster deployment and reduced downtime. Reference documentation for [../../jdbc/jdbcref-trifork.pdf]. the DataDirect drivers can be found in a seperate document If you use other JDBC drivers than the ones bundled with the server, you need to make the server aware of them. This is depicted in Figure Right-click on the the JdbcDataSources node, and select Create JDBC Data Source from the popup menu. A dialog appears. In the dialog, click the Upload button. In the dialog which appears select which server to make the driver available for (either just a single server like "default" server or all servers in the domain) and use the Browse button to select the JDBC driver file. When you press the Upload button, the JDBC driver file will be copied to the appropriate subdirectory of the lib directory of the domain (see Section 10.2 for details of the file layout of a domain) and immediately be available on the server's classpath. Figure Uploading JDBC driver 51

62 Chapter 11. Configuration Configuring a JDBC Data Source A number of template configurations have been made for the bundled JDBC drivers. You can find these by browsing to the JDBCDataSources node in the tree view of the Management client. This is depicted in Figure All you need to do is change the connection data to fit that of your database, and they are ready to be used. You can create new JDBC data sources, either with the bundled drivers, or drivers you have uploaded as described above. To do this right-click on the JdbcDataSources node in the tree view, and select Create JDBC Data Source from the popup menu. Figure Template configurations for the bundled JDBC drivers 52

63 Chapter 11. Configuration In the inspector window for a JDBC data source, the following data can be edited: Name: Specify a name for this JDBC data source JNDI name: Specify a JNDI name for the data source to be bound in naming Driver class: Select which driver class to use from the combobox. If the driver class you want to use is not in the combobox you can type it in manually. If you do this make sure that the driver class is on the servers classpath. You can also click on the Scan button to have the combobox updated by a scan for JDBC drivers in the server's classpath CMP Type Mapping: Select one of the predefined CMP type mappings to be used for the data source Username: Specify the user name to connect to the database with Password: Specify the password to connect to the database with Connection URL: If you are using a non-xa JDBC driver, specify a connection URL. The format of the URL depends on your specific JDBC driver. Consult the driver documentation to find the specific format of the URL. For the bundled JDBC drivers the URL format is specified in the template configurations and can furthermore be found in the user documentation for the drivers [../../jdbc/jdbcref-trifork.pdf] Properties: If you are using an XA driver, specify a number of properties. Which properties you need to specify depends on your specific JDBC driver. For the bundled JDBC drivers the necessary properties are specified in the the user documentation for the drivers [../../jdbc/jdbcref-trifork.pdf] Pooled Data Sources In order to efficiently access a data source you must create a pool for it. You do this by selecting the JdbcPooledDataSources node in the tree view of the management client. Right-click the node and select Create 53

64 Chapter 11. Configuration JDBC Pool from the popup menu. This is shown in Figure Figure Creating a JDBC pool In the window which pops up, fill in the following data: Name: The name of the JDBC pool JNDI Name: The JNDI name for the JDBC Pool. This is used for looking up the JDBC pool from your application DataSource JNDI Name: From the combobox select one of your predefined data sources to create the pool for Max connections: Optionally specify the maximum number of connections to be made to the database JMS Configuration of JMS consists of two types of resources: Connection factories and destinations Connection Factories When you use JMS from your J2EE application, you need to configure connection factories and destinations. This is the case both when you use Message Driven Beans and when you want to access a JMS-provider directly from a J2EE component (such as a session bean or a servlet). To configure connection factories on the Trifork Enterprise Application Server, browse to the ConnectionFactories node in the tree view of the management client. The server comes with two preconfigured connection factories. To reconfigure one of these, select it in the tree view and edit the settings in the Inspector Manager. This 54

65 Chapter 11. Configuration is shown in Figure To create a new connection factory right-click on the ConnectionFactories node and select Create JMS Connection Factory from the popup menu. Figure Configuring a JMS Connection Factory When (re)configuring a JMS connection factory, you must fill in the following information (Client id, User name and Password are optional): Name: Specify the name of the connection factory. JNDI Name: Specify the JNDI name of the connection factory. The JNDI name is used to lookup the connection factory either directly from your J2EE components or in the deployment descriptor for a Message Driven Bean. Type: Specify the type of the connection factory. Options are Queue and Topic. Client id: You can optionally specify a client id to be used by the connection factory. User name: Specify the user name the connection factory should use when communicating with the JMSprovider Password: Specify the password the connection factory should use when communicating with the JMSprovider Destinations A JMS-provider can be preconfigured with a number of Queues and Topics. To do this go to the Destinations node in the tree view of the Management client. To edit an existing destination, simply select it in the tree view. This is shown in Figure To create a new destination, right-click on the Destinations node, and select Create JMS Destination from the popup menu. 55

66 Chapter 11. Configuration Figure Configuring a JMS destination When (re)configuring a JMS destination, you must fill in the following information: Name: Specify the name of the destination JNDI Name: Specify the JNDI name of the destination Type: Specify the type of the destination. Options are 'Queue' and 'Topic' Mail If your application needs access to sending mail via a SMTP server, you must configure a mail resource. To create a new mail resource, start the management client and use the tree view to browse to the MailResource node. Right-click on the node and select Create Mail Configuration from the popup menu. This is shown in Figure Figure Creating a new mail configuration 56

67 Chapter 11. Configuration The Mail Configuration Inspector window appears. In this window you must fill in the following information: Name: Specify the name of the mail configuration JNDI Name: Specify the JNDI name of the mail resource. This is used from your application to look up the mail resource Mail From: Specify an address which will be used in the "From" field in the headers for s sent via this mail resource Mail User: Specify a valid user name for the mailserver. This user name will be used when sending mails though the mail server Mail Host: Specify the host on which the SMTP server runs Click the create button to create the mail resource. Existing mail resources can be reconfigured by selecting the specific mail resource in the tree view and editing the properties in the Inspector Manager window. This is depicted for a mail resource called "Test" in Figure Make your changes in the Inspector window, and click the apply button to make your changes take effect. 57

68 Chapter 11. Configuration Figure Editing a mail configuration Security Realms A security realm represents a distinct database of users and groups. It is possible to create and manage new security realms through the management tool. Security realms are attached to System Containers in the System Container create tool and inspector (see Section 11.9). Two realm implementations are supported: File based - Represents a user database in a local file, managed locally from the server process. LDAP based - Uses an external LDAP server as the user database. A number of configuration options makes it possible to connect to different LDAP servers (e.g., OpenLDAP, Novell edirectory, Microsoft Active Directory, and others). By default, the "default" security realm is created. This realm is based on the internal file based realm implementation. 58

69 Chapter 11. Configuration Creating Security Realms Security realms may be added by right-clicking the Security node, and from the popup menu selecting Create Security Realm. A name must be entered into the name field and a realm implementation class must be selected in the Realm Class field. Optionally, the description field may also be edited at this point. It is not possible to edit "realm specific properties" at this point (see Section on how to edit these) Managing Security Realms By right-clicking a security realm and then selecting the Inspect action, it is possible to modify the description and realm class of a realm. In addition, it is possible to edit any realm specific properties that may be available. These are visible in the realm specific properties table when a realm is inspected. Properties specific to File Based realms There are no realm specific properties for File Based realms. Properties specific to LDAP Based realms The following realm specific properties are available for LDAP Based realms: providerurl - A URL string that "ldap://localhost:389/dc=trifork,dc=com". identifies the LDAP service to use, e.g., userbasedn - Defines the placement of user objects in the LDAP tree relative to the provider URL, e.g. "ou=people". usernameattribute - The name of the attribute holding the user name, e.g., "cn". groupbasedn - Defines the placement of group objects in the LDAP tree, relative to the provider URL, e.g. "ou=groups". groupnameattribute - The name of the attribute holding the name of a group. groupmemberattribute - The name of the group attribute holding the name of a member user, e.g, "member" Threadpool To configure the size of the threadpool, select the Threadpool node in the tree view. In the Inspector Manager window, change the size of the threadpool. Click the apply button to save your changes. This configuration is shown in Figure Figure Configuring the threadpool size 59

70 Chapter 11. Configuration EmbeddedDB The Trifork Enterprise Application Server comes bundled with the HyperSonic SQL database. The database is running as an embedded database, and is therefore by default started when the server starts. Furthermore, a JDBC data source called InternalDB is created by default, and two pooled data sources uses this data source. These are called SystemDB and TriforkDB. See Section 11.3 for information on data sources in the Trifork Enterprise Application Server. The embedded database is by default running on port If you for some reason want to change this you have to do the following: Browse to the hypersonic node in the tree view of the management client In the Inspector Manager window, change the port number in the Port field and click the apply button The data source using the embedded database is configured to use the default port. You will also have to change this. To do this: Select the InternalDB node in the tree view of the Management client. In the Inspector Manager window go to the Connection URL field Add the following to the end of the URL: :<your_new_port>, see Figure Figure Changing the port of the embedded database 60

71 Chapter 11. Configuration It is also possible to disable the embedded database altogether. To do this, inspect the hypersonic node and deselect the Enabled checkbox located in the Inspector Manager window. Note The JMS implementation is dependent on the data source pool called SystemDB. By default this data source uses the embedded database. Therefore, if you disable the embedded database, you must reconfigure the SystemDB to use another database System Containers System Containers (see Section 4.1.2) can be found in the tree view under the SystemContainers node (at the same level as the Resources node). This is shown in Figure Figure Browsing system containers 61

72 Chapter 11. Configuration Creating System Containers To create a new system container, right-click the SystemContainers node, and from the popup menu select Create System Container. A dialog window pops up, see Figure 11.17, in which you type the information necessary for defining a system container: Name: The name of the new system container. The name must be unique. Description: An optional description of the system container. Security Realm: The security realm governing security validation. The Security Realm is selected from the list of realms, defined under the Security Resource node. Auto Restart: Specify that the new system container automatically shall detect changes (updates) to the archives deployed into the container. Upon changes the archive is redeployed and the system container is restarted. Monitoring interval: Specify the number of seconds between the system container check for changes to deployed archives. This field is only enabled if Auto Restart is enabled. Click the create button to create the system container. The process is shown in Figure When the system container has been created, it is automatically started. Figure Creating a system container 62

73 Chapter 11. Configuration Managing System Containers A number of actions can be performed on existing system containers. Common to these are that they are accessed by right-clicking the system container in question, and then selected from the popup menu. This is illustrated in Figure Figure Performing actions on an existing system container 63

74 Chapter 11. Configuration As can be seen in Figure the following actions can be performed on a system container. Deploy - this will bring up a dialog asking for information on which archive to deploy into the system container, and other data for the deployment. Click the Deploy button to have the archive deployed. The process is illustrated in Figure Start - starts the system container if it is stopped. A system container needs to be started in order to serve requests. Stop - stops the system container if it is running. When a system container is stopped it cannot serve requests. Restart - performs a Stop followed by a Start Remove - Stops and removes the system container. Figure Deploying an archive to a system container 64

75 Chapter 11. Configuration Log Settings The Trifork Enterprise Application Server uses the LOG4J [ system to perform logging. This section describes how to control the logging for: The server logs The Application Client log The trifork command line tool log Configuring server logging The Trifork Enterprise Application Server produces a number of log files for each server instance. These are stored in the logs directory of your domain. See Section for details on the layout of the logs directory. Using the default log configuration, three log files will be created: server.log: this log file contains logged information about the status of the server user.log: this log file contains log entries logged with the ServletContext.log() method access.log: the web container can be configured to create an access log for HTTP access. These log entries are stored in this file By default, each of these log files are configured to use RollingFileAppender's, meaning that when the logfile reaches a certain limited size, a backup copy of the logfile will be taken, and a new empty logfile will be started. By default, the logfile will be rolled, when it reaches 10 MB in size, and 5 backups will be kept. 65

76 Chapter 11. Configuration You can change these limits by going to your domain directory and editing the /config/<server_name>log4j-server.xml file. As an example, to change the configuration of the server.log to be rolled when it reaches 50 MB and keep 10 backups, edit the following part of the configuration file: <appender name="server_log" class="org.apache.log4j.rollingfileappender"> <param name="file" value="log/server.log"/> <param name="append" value="true"/> <param name="immediateflush" value="true"/> <param name="maxfilesize" value="10mb"/> <param name="maxbackupindex" value="5"/> <layout class="org.apache.log4j.patternlayout"> <param name="conversionpattern" value="%d %-5p %m%n"/> </layout> </appender> and change it to: <appender name="server_log" class="org.apache.log4j.rollingfileappender"> <param name="file" value="log/server.log"/> <param name="append" value="true"/> <param name="immediateflush" value="true"/> <param name="maxfilesize" value="50mb"/> <param name="maxbackupindex" value="10"/> <layout class="org.apache.log4j.patternlayout"> <param name="conversionpattern" value="%d %-5p %m%n"/> </layout> </appender> The access.log log file contains logging information on requests to the web container (Servlets, JSPs, HTML document etc.). To turn on the access log you have to edit the following part of the configuration file: <!-- Setup access.log --> <category name="accesslog" additivity="false"> <!-- Replace "warn" with "info" to enable access.log --> <priority value ="warn" /> <appender-ref ref="async_access" /> </category> and change the "priority value" to "info": <!-- Setup access.log --> <category name="accesslog" additivity="false"> <!-- Replace "warn" with "info" to enable access.log --> <priority value ="info" /> <appender-ref ref="async_access" /> </category> In the same manner you can turn on/off the server.log and the user.log (although we do not recommend doing so). The rest of the server logging configuration file contains configurations which can be used by the Trifork Technologies support staff if they are contacted. They should therefore not be edited by end users Configuring Application Client Logging When you are executing a J2EE Application Client on the Trifork Enterprise Application Server, log output from the clientcontainer will be saved to a file named trifork-client.log. This file will be stored in the directory from where you started the Application Client. 66

77 Chapter 11. Configuration If you need to change how the logging is performed, you should go to your domain directory and edit the clientconfig/log4j-client.xml file Configuring the Trifork Command Line Tool Logging The trifork command line tool also performs logging. However, the output is not written to a file, but is instead printed in the console, from where the command is executed. Generally you will not have to change the configuration of this log, but if you do, the configuration file is called <TRIFORK_INSTALL_DIR>/config/log4j-tools.xml Relocating Server Ports The Trifork Enterprise Application Server uses a number of default ports. In some cases you may want to change the default value of these ports. An example of such a case could be, if you need to run more than one Trifork Enterprise Application Server on a single machine. To do this, you have to do the following : Change the HTTP and HTTPS ports of the default HTTP Endpoint - this is described in Section Make sure that AJP is disabled for the endpoint Change the port of the embedded database - this is described in Section 11.8 Change the naming port - To do this go to your domain directory and edit the file config/<your_server_name>/server.properties. Uncomment the trifork.server.port property, and change the value 67

78 Chapter 12. Command Line Tools While most of the configuration of the Trifork Enterprise Application Server can be done graphically by using the management client, it is often a necessity to be able to configure a server from the command line and/or scripts. The Trifork Enterprise Application Server provides tools for both of these two needs: Command line tools: In the bin directory of each domain a command called trifork can be found. This tool can be used for most of the configurations described in this guide. In Chapter 26 you can find a complete reference of the functionality of this tool. Script tool: The Trifork Enterprise Application Server provides Ant [ tasks for most of the functionality of the trifork tool. In Chapter 27 a complete reference of the Ant tasks is provided. 68

79 Chapter 13. Web Server Integration It is possible to integrate the Trifork Enterprise Application Server with a number of different web server products, by means of the AJPv13 protocol (Apache Java Protocol version 13). In the typical setup, the web server is put in front of the Trifork Enterprise Application Server, and forwards only selected requests to the Trifork Enterprise Application Server (e.g., all requests that hit servlets and JSPs). Note that it is not in general necessary to supplement the Trifork Enterprise Application Server with a separate web server, since the Trifork Enterprise Application Server already includes a full-featured web server. However, there are a number of potential reasons for wanting to make use of this combination: A complex web server configuration is already deployed and/or well understood, and there is a wish to keep this intact. This could be the layout of static content or the specific security setup. It is believed that the web server can serve static content faster that the Trifork Enterprise Application Server (if this is the only reason, it should be verified that serving static content is in fact a bottleneck and that the combined setup is in fact faster than a setup involving only the Trifork Enterprise Application Server) Specialized features of the web server that are not available in Trifork Enterprise Application Server are needed (e.g., URL rewriting). The most important drawback of using a separate web server is probably the increased complexity. This will inevitably make it more difficult to understand, configure and debug an installation Configuring Web Server Integration Configuring the Trifork Enterprise Application Server In order to make a web application available for access via the AJP v13 protocol, you must enable the AJP protocol on the HTTP Endpoint the web application uses. Unless you have specified your own HTTP Endpoint this will be the endpoint called DEFAULT_ENDPOINT. The default setting for this endpoint is to have AJP enabled. To reconfigure a HTTP Endpoint, right-click the endpoint in question in the tree view in the management client and select Inspect from the popup menu. Enable or disable AJP by clicking the choicebox. This is shown in Figure 13.1 Figure Configuring AJP for an HTTP Endpoint 69

80 Chapter 13. Web Server Integration See also Section 11.2 for detailed information on how to configure HTTP Endpoints Configuring the Web Server The Web Server must be configured to use the mod_jk AJP module, which is a plugin for the AJP protocol. Generally, the Web Server should be configured exactly as for integration with the Tomcat web container. Only v13 of the protocol is supported by the Trifork Enterprise Application Server (the plugin also supports v11) Configuring Apache Below is an example configuration file for the mod_jk plugin: # conf/mod_jk.properties worker.list=ajp13 worker.ajp13.type=ajp13 worker.ajp13.host=localhost worker.ajp13.port=8009 The following goes into the Apache main configuration file (usually httpd.conf): # mod_jk configuration in httpd.conf LoadModule jk_module modules/mod_jk.dll AddModule mod_jk.c JkWorkersFile conf/mod_jk.properties # Send all jsp files through mod_jk JkMount /*.jsp ajp13 (Hint: The Tomcat web container has a feature for automatically generating an Apache configuration file for a particular web application. You can use Tomcat for generating this file and then use the configuration file in 70

81 Chapter 13. Web Server Integration combination with the Trifork Enterprise Application Server). 71

82 Chapter 14. Public Web Application The Trifork Enterprise Application Server has a built-in web application, with the context path /public. This is an inplace deployed application (see inplace deployment) where a user can check the layout of html and jsp files, without deploying them first. The Public web application is placed in the <DOMAIN_NAME>/servers/<SERVER_NAME>/public Default Deployment Descriptor The Public web application also contains a reduced web.xml deployment descriptor, which all other web applications inherit from. The settings that other web applications inherit are MIME mappings and welcome files. In future releases of Trifork Enterprise Application Server, it is planned to support error pages as well. To override the default settings, just insert the MIME mappings or welcome files in the web.xml deployment descriptor for the user application. Example The Public web.xml deployment descriptor <web-app> <mime-mapping> <extension>abs</extension> <mime-type>audio/x-mpeg</mime-type> </mime-mapping> <mime-mapping> <extension>ai</extension> <mime-type>application/postscript</mime-type> </mime-mapping> <! > <welcome-file-list> <welcome-file>index.html</welcome-file> <welcome-file>index.htm</welcome-file> <welcome-file>index.jsp</welcome-file> </welcome-file-list> </web-app> 72

83 Chapter 15. Monitoring a Running Server When the server is running, the Trifork management client gives you a number of options for monitoring it. At the moment you have two options (more options for management are planned for future releases): Use the Server monitor Watch individual statistics for a number of resource types These two options are described in the following sections Server Monitor The server monitor is a small graphical view of your server. It can be invoked by selecting the server you want to monitor from the tree view. Right-click on the server node, and from the popup menu select Show Server Statistics. As illustrated in Figure 15.1 this will bring up the Server Monitor window. Figure The Server Monitor In the Server Monitor you get a graphical view of: How much memory the Java Virtual Machine is using. The threadpool status. This includes information on: Maximum number of threads in the pool - this number can be changed. See Section 11.7 for information on how to do this The number of threads currently in the pool How many of these threads are currently in use 73

84 Chapter 15. Monitoring a Running Server Statistics Beside the Server Monitor it is possible to view statistics for a number of resources. To view these, use the tree view to browse to a resource. If the resource provides statistics it will have a child node called Statistics. Opening this node you will see which statistics this resource provides. To view the individual statistic, right-click on it and select Inspect from the popup menu. Below, a number of examples of statistics are shown. Statistics for more resources are planned for future releases. Figure Statistics for a deployed Servlet Figure Statistics for a deployed Entity EJB 74

85 Chapter 15. Monitoring a Running Server Figure Statistics for the heap size of the Java virtual machine 75

86 Chapter 15. Monitoring a Running Server 76

87 Chapter 16. J2SE Administration Application Client Beside the easy distribution of J2SE application clients that client launcher system provides (see Section ), the Trifork Enterprise Application Server features advanced functionality for managing and monitoring running application clients. Using these features it is possible to Ask a single or a set of running application clients to shut down. Broadcast user specified messages to individual or sets of connected application clients. Get statistical information on how many applications clients are running and their state. You must do two things to take advantage of the features provided by the J2EE Application client administration system: Add some simple code to your application client in order to e.g. handle the broadcasted messages in the appropriate manner. Use the command line tools for accessing the functionality. In the following sections, the J2EE Application client administration features will be described in detail Stopping clients The most simple functionality of the application client administration system is the ability to ask an application client to shut down. You do not have to add any code to your application client to take advantage of this functionality. To stop a client, you must use the following command: trifork client stopclients By issuing the command without any options, all application clients connected to the server in question will be asked to shut down. If you need to stop a specific client or a number of clients you must use the -receivers option. The option takes a name of a single client or a comma separated list of client names (without any spaces) as its argument. To see the names of the connected clients use the functionality described in Section Broadcasting Messages Besides stopping clients, it is possible to broadcast messages to them as well. This could e.g. be useful to notify the users that the client will be closed in 15 minutes. In order to broadcast a message to the clients you must use the following command: trifork client publishmessage The message to publish can be specified in two parts: the subject and the body. To specify these, use the subject and -body options respectively. As with the functionality described above (see Section 16.1) the receivers option can be used to control which clients receives the message Application Client Implementation Requirements In order for the application client to use the published messaged for anything, e.g. present them to the user, some simple code must be added to your application client. You need to do two things: implement a simple lis77

88 Chapter 16. J2SE Application Client Administration tener interface and register it with an EventNotificator TriforkAppClientMessageListener The listener interface you need to implement is: com.trifork.eas.api.clientcontainer.triforkappclientmessagelistener. The interface only contains a single method called newmessage. This method is called whenever a new message is published to the client, thus allowing the application client to take the appropriate action. The newmessage takes a com.trifork.eas.api.clientcontainer.messageevent as its single parameter. Using this you can call the getsubject and getbody methods to get the subject and body of the message EventNotificator In order to receive messages through your implementation of the TriforkAppClientMessageListener interface you must register your implementation with the EventNotificator object in the client container. The EventNotificator object is bound in the client containers naming implementation with the following name: java:comp/env/trifork/eventnotificator. Having obtained a reference to the EvenNotificator, you must register your listener implementation with the EvenNotificator using registerlistener method. If your TriforkAppClientMessageListener interface implementation is called MyAppClientMessageListener, the above could be implemented in the following way: EventNotificator eventnotificator; try { Context ctx = new InitialContext(); Object o = ctx.lookup("java:comp/env/trifork/"+eventnotificator.jndi_name); eventnotificator = (EventNotificator)PortableRemoteObject.narrow(o, EventNotificator.class); } catch (NamingException ne) {} TriforkAppClientMessageListener listener = new MyAppClientMessageListener(); eventnotificator.registerlistener(listener); Monitoring Connected Clients The final functionality of the application client administration system is the ability to get a list of connected clients. This is done by issuing the following command: trifork client listclients This will provide you with a list of the clients which are currently connected. How the listing is presented depends on whether you implement some extra functionality in your application client Default Listing If you do not add any extra code to your application client you will get the default listing. The default listing of the connected clients will simply present each client as the name of the machine it is running on. Furthermore, each client will be presented as "Inactive" Extended Listing By adding a small amount of code to your application client, it is possible to get a more detailed listing of the connected clients. You can extend the information presented in the listing in two ways: a custom name for the application client and information on whether the connected application client is active or not. In both cases all you need to do is to call a method on the EventNotification presented above (see Section 16.2) Application Client Name As mentioned above each application client will by default have the same name as the machine it is running on. If you for some reason want to change this (e.g. to change it to reflect which user is logged into the client), all you have to do is call the setname method on the EventNotificator. This name will then be used when making listings of connected clients or when broadcasting user messages and stop messages to the specific client. 78

89 Chapter 16. J2SE Application Client Administration Client Status Even though a client is connected to the server there is no guarantee that it is actively being used. Therefore it will by default have the status of Inactive. If you want to have more information on your application clients you can call the iamactive method on the EventNotificator to signal that the application client is actively being used. You can e.g. call the method each time a button is being clicked in the application clients GUI. When you do this the listing of connected clients will change, so instead of reporting the client as Inactive, the date and time for the last time the iamactive method was called will be presented Configuration properties The application client administration system can be configured with two properties: appclientadmin.polling.period and appclientadmin.client.timeout. In order to understand the meaning of these two properties the following paragraph contains a short description of the implementation of the system. When using the application client administration system the server keeps track of two data structures: one for messages published to the client and one to represent the connected clients. The application clients contact the server at a specified interval, checking to see if new messages have been posted for them and telling the server that they are still connected. This means that when you use one of the three trifork client commands mentioned in this chapter, the command is only talking to the server, while the server and clients are talking to each other all the time at defined intervals. This also means that when you publish a message it will not be published to the clients instantly but first when the clients "check in" the next time, and the listing of connected clients is only a snapshot of how the server sees the status at the time the command was issued. While default values have been selected for how often the clients should connect to the server, you may want to change this depending on e.g. your network setup or specific requirements regarding the reliability of the commands. appclientadmin.polling.period - use this property to specify how often the clients should connect to the server. The value specified is in seconds and the default value is five seconds appclientadmin.client.timeout - this property is used to control when the server should consider a client disconnected. The default value is three times the value of appclientadmin.polling.period 79

90 Part VI. Deploying to the Trifork Enterprise Application Server This guide describes how to deploy J2EE application and resource archives into the Trifork Enterprise Application Server.

91 Chapter 17. Overview This guide describes how to prepare and deploy J2EE applications for the Trifork Enterprise Application Server. The steps involved in doing this are: Setting up the development environment for compiling J2EE based applications. Chapter 18 describes how to do this. Packaging the application as a J2EE archive. This generally means packaging the components of the application into one or more of the standard J2EE deployable archive types: enterprise archive, ejb archive, web archive, resource archive. J2EE deployment descriptors (xml files) describing services provided and expected by the application components must be included in the archive. Packaging J2EE applications for the Trifork server is further detailed in Chapter 19. Writing a Trifork specific deployment descriptor, describing deployment relevant information that cannot be expressed by the standard J2EE deployment descriptors. An important part of this is binding the resource needs of the application to configured resources in the JNDI namespace of the server. Chapter 20 provides further details of the Trifork deployment descriptor. Deploying the application archive into the Trifork Enterprise Application Server. This is described in Chapter 21. This Guide describes how to manually package and deploy J2EE applications for the Trifork Enterprise Application Server. For non-trivial applications this can be a both complicated and time consuming task. An good alternative will in many cases be to use the Trifork Assembly Tool, described in Part VII. The Trifork Assembly Tool is a graphical tool that automates and guides most of the activities need for packaging and deploying J2EE applications for the Trifork Enterprise Application Server. Another alternative is to use automated build tools such as Ant for packaging and deploying archives. 81

92 Chapter 18. Setting up the Development Environment When developing J2EE applications, it is necessary to tell the Java compiler where to look for external libraries containing standard J2EE classes and interfaces for such things as EJBs, servlets and transactions. When using the Trifork Enterprise Application Server these external libraries reside in TRIFORK_INSTALL_DIR/lib/ext. Use the following syntax to include external directories to the Java compilation: Example ~] javac -extdirs $TRIFORK_INSTALL_DIR/lib/ext Integrated in an Ant build environment, it may be done the following way: Example <target name="build.my.j2eeapp"> <property name="ext.dirs" value="<trifork_install_dir>/lib/ext" /> <property name="classpath" value="your_classpath" /> <javac srcdir="src" destdir="classes" classpath="${classpath}" extdirs="${ext.dirs}" /> </target>... 82

93 Chapter 19. Packaging J2EE applications The J2EE specifications specify how applications must be packaged into archives before they can be deployed into a J2EE compatible application server (such as Trifork Enterprise Application Server). A number of archive types are defined, all based on the jar archive format with some additional constraints on the content structure. For each archive type, the J2EE specifications define the files required and their location in the directory structure. Archives may include Java classes for EJBs and servlets, Web pages, JSP pages and other supporting files, XML-formatted deployment descriptors, and JAR files containing other components Trifork Specific Archive Formats In addition to the standard J2EE jar archive formats, Trifork Enterprise Application Server supports some variants of the J2EE formats that can be more convenient, especially in development environments where rapid redeployments are often needed. These variants are denoted Inflated Archives and Mapped Archives. Common to these archive types is that the data copying needed for creating the standard archive types has been eliminated. Inflated and Mapped archives are especially valuable in combination with Trifork inplace deployment (see Section ). By combining inflated/mapped archives with inplace deployment it is possible to create a setup where the Trifork Enterprise Application Server is executing directly on, e.g., the.class and.jsp files of the development environment. The benefits of inflated/mapped archives are twofold: The overhead of bundling together the components of a J2EE archive can be substantial, especially in larger projects. Although this task can be automated by tools such as Ant, the time spent bundling archives may be counterproductive in a development cycle. By letting the Trifork Enterprise Application Server execute directly on the same file instances as the development environment, it is possible to take advantage of, e.g., the automatic reload of JSP pages, supported by the Trifork Enterprise Application Server. That is, the development cycle of JSP pages may be as simple as saving a JSP file in an editor, followed by hitting the reload button in a browser. If the development environment supports hot class replacement during debug sessions, it is possible to replace a loaded application class without server restart or redeploy in the middle of a session, if the Trifork Enterprise Application Server is executing the class files that are output by the development environment Inflated Archives Inflated Archives refer to applications that are represented as directory trees with the exact same content and structure as the the corresponding J2EE jar based archive type, i.e., inflated archives are really just unpacked J2EE archives. All trifork commands accept inflated archives anywhere a jar file is accepted. Both top level archives (e.g., an enterprise archive) and nested archives (e.g., a client jar within an enterprise archive) may be inflated. It is possible to combine standard and inflated archives freely, e.g., to create the top-level archive as a jar file, with all nested archives inflated. Inflated archives are a simple mechanism for streamlining the development process in situations where it is possible to maintain a directory structure in the development environment that is compatible with the J2EE archive conventions. A typical example of this is a web archive containing JSP files and static content Mapped Archives Trifork commands that accept a J2EE archive may be provided with an xml descriptor in place of the actual archive file/directory. This descriptor maps a number of directories and files into one logical archive. The name of the mapping file must end with ".map". Both absolute and relative file system paths may be used for identifying files and directories. Relative paths in the mapping descriptor are interpreted relative to the location of the descriptor file. A typical use of the mapping feature would be to avoid copying class files generated by a development environ83

94 Chapter 19. Packaging J2EE applications ment. An example of this could look like: <?xml version="1.0"?> <jar name="app.war"> <file path="web-inf/web.xml" from="deployment/app-web.xml"/> <file path="meta-inf/trifork-app-conf.xml" from="deployment/app-trifork.xml"/> <dir path="web-inf/classes/com/trifork/app" from="../bin/com/trifork/app"/> <dir path="web-inf/classes/com/trifork/common" from="../bin/com/trifork/common"/> <dir path="web-inf/lib" from="../lib" /> <dir path="" from="jsp" /> </jar> In the example, the following directory layout is assumed: top / / / bin lib app / com / / app.map deployment / jsp / trifork /... / / app-web.xml app-trifork.xml The descriptor defines the following mappings for the logical archive: top/app/deployment/app-web.xml top/app/deployment/app-trifork.xml top/bin/com/trifork/app/* top/bin/com/trifork/common/* top/lib top/app/jsp/* -> -> -> -> -> -> WEB-INF/web.xml META-INF/trifork-app-conf.xml WEB-INF/classes/com/trifork/app WEB-INF/classes/com/trifork/common WEB-INF/lib <archive-root> It is also possible to use the jar tag recursively in the mapping descriptor, e.g., to describe a.war file nested inside a.ear file. The mapping algorithm finds the longest matching prefix, that is two file/dir entries may have path attributes with overlapping prefixes. The entry with the longest matching path wins. This means that the empty path ("") matches anything that has no other matches. If the from attribute of a file element refers to a directory instead of a file, the directory is searched for a file of the same name as the filename given in the path attribute. That is, if the directory "depl" contains a file named "web.xml", the mapping <file path="web-inf/web.xml" from="depl"/> is equivalent to the mapping <file path="web-inf/web.xml" from="depl/web.xml"/> JAR Files A file created with the Java jar utility bundles the files in a directory into a single Java ARchive (JAR) file, maintaining the directory structure. The Java classloader can search for Java class files (and other file types) in a JAR file the same way that it searches a directory in its classpath. Because the classloader can search a directory or a JAR file, you can deploy J2EE components into the Trifork Enterprise Application Server in either an "inflated" directory or a JAR file. JAR files are convenient for packaging components and applications for distribution. They are easier to copy, they use up fewer file handles than an inflated directory, and they can save disk space with file compression. The jar utility is in the bin directory of your Java Development Kit. If you have javac in your path, you also have jar in your path. The jar command syntax and behavior is similar to the Unix tar command. The most common usages of the jar command are: Create a JAR file named jar-file containing listed files. If you include a directory in the list of files, all files in that directory and its subdirectories are added to the JAR file. 84

95 Chapter 19. Packaging J2EE applications jar cf jar-file files... Extract (unbundle) a JAR file in the current directory. jar xf jar-file List the contents of a JAR file. jar tf jar-file Packaging Web Components A web component is represented by a directory hierarchy. The root of this hierarchy serves as a document root for the files that are part of the application. For example, a web application with a directory /homebank containing an index.html file can be served to satisfy a request for /homebank/index.html. A special directory exists within the application hierarchy named WEB-INF. This directory contains all things related to the application that are not in the document root of the application. The WEB-INF node is not part of the public document tree of the application. No file contained in the WEB-INF directory may be served directly to a client by the container. The contents of the WEB-INF directory is: The /WEB-INF/web.xml deployment descriptor. The /WEB-INF/classes/* directory for servlet and utility classes. The classes in this directory are available to the application classloader. The /WEB-INF/lib/*.jar area for Java ARchive files. These files contain servlets, beans, and other utility classes useful to the web application. The web application class loader can load classes from any of these archive files. The web application classloader loads classes from the WEB-INF/classes directory first, and then from library JARs in the WEB-INF/lib directory. The following is an example of a web application directory layout: index.html homebank.jsp images/logo.jpg WEB-INF/web.xml WEB-INF/classes/dk/eos/account/AccountServlet.class WEB-INF/lib/oro.jar You can find the DTD for the web.xml file at Packaging EJB Components EJB components consist of a number of class files and an ejb-jar.xml file. There may also be certain libraries (jar files) needed by the application. All of these have to be placed in the following structure: <package>/*.class META-INF/lib/*.jar META-INF/ejb-jar.xml 85

96 Chapter 19. Packaging J2EE applications e.g. dk/eos/account/account.class dk/eos/account/accounthome.class dk/eos/account/accountejb.class META-INF/lib/oro.jar META-INF/ejb-jar.xml You can find the DTD for the ejb-jar.xml file at Packaging J2EE Application Clients J2EE application clients are Java programs (e.g. Swing applications) which are going to access one or more EJB(s) deployed on the application server. The application clients run in a separate VM from the application server. Application clients consist of a number of class files (i.e. the client itself), all home and remote interfaces for all EJBs which are going to be accessed by the application client, and an application-client.xml file. Furthermore, certain libraries (jar files) may also be needed by the application. All of these files have to be placed in the following structure: <package>/*.class <package>/*.class (home and remote interfaces) META-INF/lib/*.jar META-INF/application-client.xml e.g. AccountClient.class dk/eos/account/account.class dk/eos/account/accounthome.class META-INF/application-client.xml This structure then needs to be packed in a jar archive, e.g. app-client.jar and placed in the ear archive (see Section 19.7 for further information on how to create an ear archive). You can find the DTD for the application-client.xml file at Packaging Connectors A Resource Archive consists of a deployment descriptor in META-INF/ra.xml and a number of nested jar files containing java class files. Other content may also be included in the resource archive such as native libraries needed by the java classes Packaging Enterprise Applications An Enterprise archive (ear) consists of modules of four different kinds. It is not required that modules of all four types are present in the archive. The enterprise archive may furthermore contain any number of modules of each type. Web modules, placed in.war files Enterprise Java Beans, placed in.jar files Application clients, placed in.jar files Connectors, placed in.rar files 86

97 Chapter 19. Packaging J2EE applications These archives are bundled together in the enterprise archive, which simply is a jar archive with an.ear extension. The META-INF subdirectory in the.ear file must contain an application.xml deployment descriptor file, which identifies the modules packaged in the.ear file. The following is an example of an EAR file structure: homebank.war account.jar accountclient.jar META-INF/application.xml You can find the DTD for the application.xml file at 87

98 Chapter 20. Descriptor Trifork Deployment While most of the deployment information is found in the portable deployment descriptors application.xml, web.xml, and ejb-jar.xml, there are still crucial details that are not available. These are generally nonportable specifications of how things are tied together; which are described in the vendor-specific deployment descriptor. For the Trifork Enterprise Application Server such specifications are described in the Trifork specific deployment descriptor, trifork-app-conf.xml. As has already been described, the Trifork specific deployment descriptor can either be stored inside your archive in META-INF/trifork-app-conf.xml, or in a trifork-app-conf.xml given on the command line to the trifork archive deply command. This chapther describes most of the details of what can go in the Trifork deployment descriptor; please refer to Chapter 32 for the DTD. The trifork deployment descriptor --- trifork-app-conf.xml contains information that cannot be expressed in the deployment descriptors defined by the J2EE specifications. The information that can be expressed in Trifork deployment descriptor can be divided into: JNDI binding information connecting applications to deployed beans (<ejb-ref>) and resources resource(<ref>). Web application setup (context-root and HTTP endpoint). Security setup (role mappings), mapping J2EE security roles to user principals in a non-j2ee security domain. The trifork-app-conf.xml file can be send to the server in two ways: By including it in the archive. The file should be placed in the META-INF directory of the top level archive (.jar,.war,.rar or.ear file). By specifying it to the trifork archive deploy command (see Section 21.2) Configure global resources (users and datasources) Next step is to configure the Trifork Server to be ready to accept the application. This envolves setting up DataSources and setting up users Configure DataSources If your application need to access one or more DataSources, these have to be configured in the Trifork Server first. DataSources are configured using the management console. Each DataSource is bound to one or more JNDI names (one for each pool), and these JNDI names can be entered in the trifork-app-conf.xml to bind the application to a specific DataSource. See Section 11.3 for a detailed description on configuring DataSources Configure users If your application uses J2EE security, your would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. The Trifork Enterprise Application Server also has builtin support for using an external LDAP server, see 88

99 Chapter 20. Trifork Deployment Descriptor Section To set up users and groups in the internal user database, you can use the trifork realm command: Add a new user: trifork realm adduser <username> <password> Add a new group: trifork realm addgroup <groupname> Add a user to a group: trifork realm addmember <groupname> <username> Change password for user: trifork realm updateuser <username> <password> See Section for a detailed description Binding EJBs and Resources One of the most important roles of the Trifork system descriptor is to describe resource bindings. These can be bindings required by the components being deployed, referencing system resources such as database connections. For EJBs the Trifork deployment descriptor is also used to specify a global JNDI name by which a certain EJB is available to other components. The following table Table 20.1 outlines some of the most important kinds of resource reference that are made in an J2EE application. In the following, we will go through and explain each of these cases in more detail. Table Bindings To EJB in same archive From EJB use ejb-ref w/ From Web application From Appclient ejb- use ejb-ref w/ ejb- use ejb-ref w/ link To EJB in other archive To JDBC resource To JavaMail resource To environment entry use ejb-ref use resource-ref use resource-ref link use ejb-ref use resource-ref w/ use resource-ref ejb- link use ejb-ref use resource-ref w/ use resource-ref mail-resource-conf mail-resource-conf mail-resource-conf use env-entry use env-entry use env-entry w/ Consider in this example, an enterprise archive with the following structure: tyfooninc.ear +- business.jar +- orders.war +- customer.war +- admin.jar (EJBs for core business) (order management web system) (customer relations web system) (Swing client application) The enterprise archive tyfoooninc.ear contains the entire busineess management system for Tyfoon Industries, Inc. The EJB-jar file, business.jar contains all the EJBs for the business model, customer.war, orders.war contain two separate web applications, and admin.jar contains a J2EE client program (a Swing application) that also needs access to the various resources in the system. 89

100 Chapter 20. Trifork Deployment Descriptor Referencing EJBs in the Current Archive When a J2EE component (EJB, web application or client application) needs to refer to an EJB located in the same deployment archive (.jar or.ear file), the best way to establish such a resource reference is by using an ejb-ref with an ejb-link specification. This way there is no need to specify anything in the Trifork specific deployment descriptor. For now, let us assume that business.jar contains three EJBs: a session bean acting as facade, and two entity beans, for customers and orders. The deployment descriptor for business.jar might look something like this: <ejb-jar> <description> Business Model for Tyfoon Industries, Inc. </description> <enterprise-beans> <entity> <description>a Customer</description> <ejb-name>customerejb</ejb-name> <home>com.tyfoon.customerhome</home> <remote>com.tyfoon.customer</remote>... </entity> <entity> <description>an Order</description> <ejb-name>orderejb/ejb-name>... </entity> <session> <description>business Facade</description> <ejb-name>tyfoonbusinessfacade</ejb-name> <home>com.tyfoon.tyfoonbusinesshome</home> <remote>com.tyfoon.tyfoonbusiness</remote>... </session> </enterprise-beans>... </ejb-jar> Inside the Business Facade, the bean needs to access customer and order beans. To do this, the descriptor for the facade must be extended to reflect that the business facade needs access to these beans. Thus, we will extend the descriptor with the following: <ejb-jar>... <session> <description>business Facade</description> <ejb-name>tyfoonbusinessfacade</ejb-name> <home>com.tyfoon.tyfoonbusinesshome</home> <remote>com.tyfoon.tyfoonbusiness</remote> <ejb-ref> <ejb-ref-name>ejb/order</ejb-ref-name> <ejb-ref-type>entity</ejb-ref-type> <home>com.tyfoon.orderhome</home> <remote>com.tyfoon.order</remote> </ejb-ref> <ejb-ref> <ejb-ref-name>ejb/customer</ejb-ref-name> <ejb-ref-type>entity</ejb-ref-type> <home>com.tyfoon.customerhome</home> <remote>com.tyfoon.customer</remote> </ejb-ref>... </session>... </ejb-jar> With this descriptor, it doesn't say which bean is actually bound to the names ejb/order and ejb/customer. What the above descriptor means is that the facade bean can include code in the form:... 90

101 Chapter 20. Trifork Deployment Descriptor Context ctx = new InitialContext(); Object ch0 = ctx.lookup ("java:comp/env/ejb/customer"); CustomerHome ch = (CustomerHome) javax.rmi.portableremoteobject.narrow (ch0, CustomerHome.class);... Customer ch = ch.create(); To specify, that the linked bean is exactly the Customer bean located in the same archive, the deployment descriptor needs to be extended further. In the following, an ejb-link tag has been added, specifying exactly which EJB is the result of looking up the java:comp reference. <ejb-jar>... <session> <description>business Facade</description> <ejb-name>tyfoonbusinessfacade</ejb-name> <home>com.tyfoon.tyfoonbusinesshome</home> <remote>com.tyfoon.tyfoonbusiness</remote> <ejb-ref> <ejb-ref-name>ejb/order</ejb-ref-name> <ejb-ref-type>entity</ejb-ref-type> <home>com.tyfoon.orderhome</home> <remote>com.tyfoon.order</remote> <ejb-link>orderejb</ejb-link> </ejb-ref> <ejb-ref> <ejb-ref-name>ejb/customer</ejb-ref-name> <ejb-ref-type>entity</ejb-ref-type> <home>com.tyfoon.customerhome</home> <remote>com.tyfoon.customer</remote> <ejb-link>customerejb</ejb-link> </ejb-ref>... </session>... </ejb-jar> If you want to reference an EJB in this way from the client application, all you need to do is to include a reference of the same kind in the application-client deployment descriptor for admin.jar. <application-client>... <ejb-ref> <ejb-ref-name>ejb/customer</ejb-ref-name> <ejb-ref-type>entity</ejb-ref-type> <home>com.tyfoon.customerhome</home> <remote>com.tyfoon.customer</remote> <ejb-link>customerejb</ejb-link> </ejb-ref>... </application-client> Now, if the system includes more than one bean with the ejb-name CustomerEJB it is necessary to disambiguate these by specifying which.jar file contains the relevant bean. As an example, the following is equivalent to the above (though more explicit): <application-client>... <ejb-ref> <ejb-ref-name>ejb/customer</ejb-ref-name> <ejb-ref-type>entity</ejb-ref-type> <home>com.tyfoon.customerhome</home> <remote>com.tyfoon.customer</remote> <ejb-link>business.jar#customerejb</ejb-link> </ejb-ref>... </application-client> The same goes for web applications, where it would look like this: 91

102 Chapter 20. Trifork Deployment Descriptor <web-app>... <ejb-ref> <ejb-ref-name>ejb/customer</ejb-ref-name> <ejb-ref-type>entity</ejb-ref-type> <home>com.tyfoon.customerhome</home> <remote>com.tyfoon.customer</remote> <ejb-link>business.jar#customerejb</ejb-link> </ejb-ref>... </web-app> Referencing EJBs Outside the Current Archive In order to reference an EJB which is outside the current deployment archive, it must be accessed via its assigned JNDI name. An EJBs JNDI name is a binding specified in the Trifork specific deployment descriptor, and binds to the home interface for that bean. The JNDI binding is a global binding, meaning that the binding is visible to all components running in the same application server. The following example illustrates how the Trifork specific deployment descriptor is used to assign a JNDI name to the beans in the business.jar archive. Since we have just one Trifork-specific descriptor for the entire ear file, this is specified in the descriptor for tyfooninc.ear: <?xml version="1.0"?> <!-- trifork-app-conf.xml for tyfooninc.ear --> <!DOCTYPE trifork-app-conf PUBLIC '-//Trifork//DTD System Configuration//EN' ' <trifork-app-conf>... <enterprise-beans> <ejb> <ejb-name>customerejb</ejb-name> <jndi-name>tyfoon/customerejb</jndi-name>... </ejb> <ejb> <ejb-name>orderejb</ejb-name> <jndi-name>tyfoon/orderejb</jndi-name>... </ejb> <ejb> <ejb-name>tyfoonbusinessfacade</ejb-name> <jndi-name>tyfoon/tyfoonbusinessejb</jndi-name>... </ejb>... </enterprise-beans> </trifork-app-conf> Notice the DOCTYPE specification for a trifork-app-conf; we will omit this for the rest of the examples in this chapter. A J2EE component anywhere in the system can look up any of these EJB's using direct JNDI references without java:comp/env prefix. Though this is definitively not recommended, it would look like this:... Context ctx = new InitialContext(); Object ch0 = ctx.lookup ("tyfoon/customerejb"); CustomerHome ch = (CustomerHome) javax.rmi.portableremoteobject.narrow (ch0, CustomerHome.class);... Customer ch = ch.create(); The reason why this is not recommended is that it increases the coupling of your system in a serious way. Suddently the code that uses such inside knowledge is dependent on the exact JNDI name of the bean itself. 92

103 Chapter 20. Trifork Deployment Descriptor The proper way to reference a bean in this situation is instead to use an ejb-ref reference, and then put information in the trifork-specific deployment descriptor as to which name the ejb-ref is tied to. In this way, you can delay the decision as to which bean it is linked to, making your bean code more reusable since the Customer EJB may be replaced by a more sophisticated one without changing the clients. Now let us assume that the sales department in Tyfoon Industries, Inc. is developing its own J2EE application, which needs to access the Customer EJB. The sales application is deployed on the Trifork Enterprise Application Server in a separate ear file, and thus we cannot use the neat ejb-link feature described above. salesapp.ear +- salesweb.war +- salesbeans.jar We must revert to using ejb-ref with the binding specified in the Trifork specific deployment descriptor. The portable deployment descriptor for the sales application might look like this: <!-- web.xml for salesweb.war --> <web-app>... <description>sales Application</description>... <ejb-ref> <ejb-ref-name>ejb/customer</ejb-ref-name> <ejb-ref-type>entity</ejb-ref-type> <home>com.tyfoon.customerhome</home> <remote>com.tyfoon.customer</remote> </ejb-ref>... </ejb-jar> As before, this deployment descriptor does not say to which actual bean this ejb-ref is tied; it only states that the sales application needs to be able to look up an entity by the name "java:comp/env/ejb/customer", expecting it to be of type com.tyfoon.customerhome. To establish the binding, we need to specify the JNDI name for the bean to be linked to in the sales application's Trifork descriptor. It might look like this: <!-- trifork-app-conf.xml for salesapp.ear --> <trifork-app-conf> <web-app> <uri>salesweb.war</uri>... <ejb-ref> <ejb-ref-name>ejb/customer</ejb-ref-name> <jndi-name>tyfoon/customerejb</jndi-name> </ejb-ref> </web-app> </trifork-app-conf> This specifies, that within the web application named SalesApp, a reference to is resolved to be a link to "tyfoon/customerejb". For this to work, obviously, the name "tyfoon/customerejb" must have been bound by some other application. The Trifork specific deployment descriptor listed above for tyfooninc.ear did just that. Now let us make the situation a bit more complex. Assuming the sales application also includes a session bean caled SalesFacade, and this bean also needs to reference the Customer EJB, it would have a portable descriptor looking like this: <!-- ejb-jar.xml for salesbeans.jar --> <ejb-jar> <description> Sales Management for Tyfoon Industries, Inc. </description> <enterprise-beans> <session> <description>sales Facade Bean</description> <ejb-name>salesfacade</ejb-name>... <ejb-ref> <ejb-ref-name>ejb/customer</ejb-ref-name> <ejb-ref-type>entity</ejb-ref-type> 93

104 Chapter 20. Trifork Deployment Descriptor <home>com.tyfoon.customerhome</home> <remote>com.tyfoon.customer</remote> </ejb-ref> </session> </enterprise-beans>... </ejb-jar> Meaning that the bean code inside SalesFacade can access the Customer EJB via java:comp/env/ejb/customer. In order to specify that this ejb-ref is actually tied to the Customer EJB, we need to extend the deployment descriptor for the sales archive: <!-- trifork-app-conf.xml for salesapp.ear --> <trifork-app-conf> <web-app> <uri>salesweb.war</uri>... as before </web-app> <enterprise-beans> <ejb> <ejb-name>salesfacade</ejb-name> <ejb-ref> <ejb-ref-name>ejb/customer</ejb-ref-name> <jndi-name>tyfoon/customerejb</jndi-name> </ejb-ref> </ejb> </enterprise-beans> </trifork-app-conf> Since the sales application is in a separate enterprise archive, it cannot reference the beans in tyfooninc.ear using ejb-link's. It must reference them using the global JNDI name space. Obviously, using global names is not desirable, but it allows one to break down a large application into several independent J2EE applications Setting up a JDBC Resource References In order to be able to use a database connection, you must first configure a JDBC data source. Please see Section 11.3 for how to do that. A JDBC data source thus configured, is a global resource available in the JNDI name space as an object implementing javax.sql.datasource. This is the case for both JDBC 1.0 and JDBC 2.0 drivers, as well as for both XA and non-xa drivers. In the case that the provided driver does not implement the necessary functionality for transaction management and connection pooling, the Trifork Enterprise Application Server provides wrappers that are automatically applied. For JDBC 1.0 data sources, these wrappers are necessarily limited to allowing connection to only one database in a given transaction, since such wrapped JDBC drivers cannot handle two-phase commit. For this reason, it is highly recommended to use XA-aware JDBC drivers, since such are designed to operate in the multi-concurrent environment found inside an application server. It is very important that J2EE applications access databases by means of pooled connections managed by the application server. Loading a JDBC driver directly is dangerous at best, since the application server has no chance of knowing of its existence, and thus no way to properly handle failures, as well as concurrent updates to multiple databases. Having set up a jdbc data source, it can be referenced using a resource-ref tag in the portable deployment descriptor ejb-jar.xml, web.xml or application-client.xml. For using an JDBC resource from an EJB, the deployment descriptor looks like this: <!-- ejb-jar.xml for salesbeans.jar --> <ejb-jar>... <enterprise-beans> <session> <ejb-name>salesfacade</ejb-name>... <resource-ref> <res-ref-name>jdbc/salesdb</res-ref-name> <res-type>javax.sql.datasource</res-type> 94

105 Chapter 20. Trifork Deployment Descriptor <res-auth>container</res-auth> </resource-ref> </session> </enterprise-beans> </ejb-jar> With such a resource reference declaration, the code inside SalesFacade can look up the data source via java:comp/env/jdbc/salesdb, and cast the result to javax.sql.datasource. But still, this doesn't say which database or which driver to use. Extra information must be added to the Trifork specific deployment descriptor, more specifically, the pool-name tag for a data-source configured in the Trifork Enterprise Application Server. If you have configured a JDBC data source bound to jdbc/oracledb, the resource described in the above deployment descriptor can be bound as follows: <!-- trifork-app-conf.xml for salesapp.ear --> <trifork-app-conf>... <enterprise-beans> <ejb> <ejb-name>salesfacade</ejb-name> <resource-ref> <res-ref-name>jdbc/salesdb</res-ref-name> <jndi-name>jdbc/oracledb</jndi-name> </resource-ref> </ejb> </enterprise-beans> </trifork-app-conf> With this setup, when the SalesFacade bean code looks up "java:comp/env/jdbc/salesdb", it will receive a data source from the connection pool named "jdbc/oracledb" as configured in the management client. See Section 11.3 for information on how to configure JDBC connection pools Setting and Overriding env-entry's The portable deployment descriptors allow you to specify so-called env-entry's (environment entries) for J2EE components. In the portable descriptors these may or may not have been assigned a value using the optional env-enntry-value element. In the Trifork specific deployment descriptor, you can set these values, and even override the values specified in the portable descriptors, in a fashion similar to ejb-refs and resource-refs. If for example Tyfoon Industries customer web system specifies an environment entry like this: <!-- web.xml for salesweb.war --> <web-app> <uri>salesweb.war</uri>... <env-entry> <env-entry-name>salesdirector</env-entry-name> <env-entry-type>java.lang.string</env-entry-type> </env-entry> </web-app> The value of the environment entry can be bound in the Trifork specific deployment descriptor with a construct like the following. <!-- trifork-app-conf.xml for salesapp.ear --> <trifork-app-conf> <web-app> <uri>salesweb.war</uri>... <env-entry> <env-entry-name>salesdirector</env-entry-name> <env-entry-type>java.lang.string</env-entry-type> <env-entry-value>jones</env-entry-value> </env-entry> </web-app> </trifork-app-conf> 95

106 Chapter 20. Trifork Deployment Descriptor The value for an environment entry appearing in the Trifork specific deployment descriptor has precedence over a value appearing in the portable descriptors. This is particularly useful if the component being deployed comes from a third party, or you don't have the source code for the component. As for web applications illustrated here, environment entries may be bound or overridden for application clients and Enterprise JavaBeans Configuring Web Applications Resources for web applications are specified in the web-app section of the Trifork specific deployment descriptor. If the current deployment archive contains more than one web application, the uri tag is used to designate which web application is meant. As an example, consider a deployment archive containing two web applications (i.e., two.war files), one called orders.war and one called customers.war. <!-- file orders-web.xml --> <web-app> <uri>orders.war</uri>... </web-app> And here is a corresponding outline for the customers web.xml: <!-- file customers-web.xml --> <web-app> <uri>customers.war</uri>... </web-app> Enabling Persistent Web Sessions By default, web sessions are lost when a system container or the complete server process is restarted. This can be avoided by adding a <persistent-sessions> tag with the value "true" to the <web-app> element. When persistent Web sessions are enabled, active sessions are serialized to individual files at container stop, and deserialized at container start. Enabling persistent sessions for the customers application would look like this: <!-- file customers-web.xml --> <web-app> <uri>customers.war</uri>... <persistent-sessions>true</persistent-sessions> </web-app> Persistent sessions make it possible to continue a session across server or system container restart. This can be useful when testing web applications manually from a web browser, for example by avoiding the necessity of repeating a login sequence each time an application is redeployed. Sessions objects that produce errors during serialization or deserialization are automatically discarded. This will normally happen if one of the objects referenced in a session has changed its method signature Setting the Context Root for a Web Application When a web application is deployed it needs to have a context root assigned in order to know to which web application an incoming HTTP request should be directed. In the Trifork Enterprise Application Server there are three ways the context root may be assigned to a web application: By assigning a context-root in the enterprise archive containing the web application. This can be done in the portable deployment application.xml descriptor. Note that there is no corresponding way of specifying the context root in a web archive, which means that there is no portable way of specifying the context root 96

107 Chapter 20. Trifork Deployment Descriptor for web applications that are deployed in standalone web archives. By assigning a context-root in the web-app section of trifork-app-conf.xml. If a context-root is assigned both in trifork-app-conf.xml and application.xml, the value defined by trifork-app-conf.xml will have effect. By not explicitly defining a context-root. In the case, the Trifork Enterprise Application Server will use the filename of the web archive minus the.war suffix as the context-root. It is an error to deploy more than one application on the same HTTP endpoint with the same context root. The following illustrates how to set up orders and customers at context roots /order and /cust respectively. With this setup, all HTTP requests beginning with are directed to the Orders web application, and all requests beginning with are delivered to the customer's web application: <trifork-app-conf>... <web-app> <uri>customers.war</uri> <context-root>/cust</context-root> </web-app> <web-app> <uri>orders.war</uri> <context-root>/order</context-root> </web-app> </trifork-app-conf> Setting up HTTP Endpoints For web applications, the port to use for servicing HTTP requests can be specified using the endpoint subtag of the web-app section. If no such endpoint tag is specified, the web application will be serviced using the server's default HTTP endpoint; see Section 11.2 for information on configuration of endpoints. The following example illustrates how to set up the webcontainer to service the Orders web application on the endpoint OTHER_ENDPOINT. <trifork-app-conf>... <web-app> <uri>orders.war</uri>... <endpoint>other_endpoint</endpoint> </web-app>... </trifork-app-conf> Packaging Connectors Deploying a connector (.rar-file) to the Trifork Enterprise Application Server is quite straight-forward. A connector can be configured in two ways, which are described in the connector part of trifork-app-conf.xml. These two ways are as follows: Overriding default configuration parameters; that is, assigining values other than those default values described in the ra.xml included in the archive. Definition of the JNDI names by which the connector is made available to components inside the container. Connectors are configured in much the same way as deployment information is added to beans and web components; the top-level deployed archive (being either an EAR or some other archive file) contains a triforkapp-conf.xml that describes all the elements in the entire deployment unit. So, if the RAR file is being deployed "alone", then the trifork-app-conf.xml describing how the connector is configured should be included in the RAR file's META-INF catalog. If the connector is to be deployed as part of an application bundle 97

108 Chapter 20. Trifork Deployment Descriptor (EAR file), then the connector is configured in the trifork-app-conf.xml included in the EAR file. Alternatively, the trifork-app-conf.xml need not be included in the archive, it can also be specified on the command line to the trifork command line tool. See Section 19.7 for description of these packaging options. A connector is only accessible from the system container it has been deployed to. If a connector needs to be made available to components in other system containers, then the connector needs to be deployed into those as well. The connection factories defined as a result of deploying a connector are only accessible to components by means of resource references from EJB and WEB components. Even though trifork-app-conf.xml defines a JNDI-name for the connector's connection factories, these are not readily available in the application server's global name space by using InitialContext lookup, but only by means of resource references Example The following is an example of a trifork-app-conf.xml defined for an XML server connector: <?xml version="1.0" encoding="iso "?> <!DOCTYPE trifork-app-conf PUBLIC '-//Trifork Technologies//DTD Trifork Application Descriptor1.0//EN' ' <trifork-app-conf> <connector> <!-- The display name should match the display name used -- in the corresponding rar file, such that if multiple -- RARs are included in the same EAR, these can be -- distinquished --> <display-name>xml Server Connector</display-name> <!-- The tag jndi-names includes one or more names by which the -- connector is visible inside a system container --> <jndi-names> <jndi-name>env/eis/xmlserver</jndi-name> </jndi-names> <!-- configuration properties appearing here must also be present -- in the RA.XML, or they will be ignored. --> <config-property> <config-property-name>connectionurl</config-property-name> <config-property-type>java.lang.string</config-property-type> <config-property-value>iiop://myhost:2045</config-property-value> </config-property> <config-property> <config-property-name>username</config-property-name> <config-property-type>java.lang.string</config-property-type> <config-property-value>xmlman</config-property-value> </config-property> </connector> </trifork-app-conf> Once this connector has been deployed to the application server, an EJB or web components can access the connector by means of a resource-ref. So the portable descriptor ejb-jar.xml or web.xml may contain a resource reference declaration such as this: <resource-ref> <description></description> <res-ref-name>eis/xmlserver</res-ref-name> <res-type>foo.bar.xmlconnectionfactory</res-type> <res-auth>container</res-auth> <res-sharing-scope>shareable</res-sharing-scope> </resource-ref> And then the specific descriptor should contain a binding that ties the resource reference to the connector's connection factory. 98

109 Chapter 20. Trifork Deployment Descriptor <resource-ref> <res-ref-name>eis/xmlserver</res-ref-name> <jndi-name>env/eis/xmlserver</jndi-name> <resource-principal> <principal>user1</principal> <password>password1</password> </resource-principal> </resource-ref> Configuring Security Roles The trifork-app-conf.xml allows mappings between the J2EE security roles defined in the portable deployment descriptors and the user and group principals of a security realm. The portable descriptors allow for specification of J2EE security roles using the security-role tag, and various security constraints based on these roles. For EJBs the constraints specify which methods can be invoked by whom, by means of specifying the role that the calling user must be part of in order to invoke a method. Similarily, web applications can have authorization constraints associated with them identifying which role is allowed to make requests for a given web resource. J2EE roles defined by security-role may be mapped to user and group principals using the role-mapping element in the Trifork specific deployment descriptor. This tag enumerates, for each role, a number of principals that are considered to be members of the given role. As an example, a role mapping may look like this: <trifork-app-conf>... <role-mapping> <role name="administrator"> <principals> <principal>peter</principal> <principal>mary</principal> </principals> </role> <role name="sales"> <principals> <principal>peter</principal> <principal>sam</principal> </principals> </role> </role-mapping>... </trifork-app-conf> This example defines a mapping between the role administrator to the named principals peter and mary and between the role sales to the principals peter and sam. In the Trifork Enterprise Application Server the default mechanism for authenticating individuals is based on a simple encrypted user/password file located in the server instance's config directory. This file can be administered using the trifork realm command (see Section 26.12). Issue the command trifork realm -help to see a command line overview. This tool allows creation and administration of a set of users and groups. 99

110 Chapter 21. Deploying Archives Creating a System Container Before an application can be deployed to the Trifork Enterprise Application Server, a system container has to be created. See Section for a description of system containers. Use the following command to create a system container: trifork system create <system name> A system container is automatically started when it has been created. To start and stop system containers, use the following commands: trifork system start <system name> trifork system stop <system name> Note: An alternative way of managing system containers is to use the Trifork Management Console, see Section Deploying Applications to the Trifork Server Deploying an Application The default way to deploy an application to the Trifork Enterprise Application Server, is by issuing the command: trifork archive deploy <system name> <archive name> where <system name> is the name of the system container, and <archive name> is the name of the JAR, WAR, EAR or RAR file. Here is an example: Deploy the Java Pet Store demo: trifork archive deploy estore petstore.ear Redeploying an Application Redeploying (updating) applications uses the same syntax: trifork archive deploy <system name> <archive name> There are no limits to the number of times an application can be reployed to the Trifork Enterprise Application Server, and no limitations to the changes in interfaces, implementation classes or deployment descriptors that can be made between redeployments. The Trifork Enterprise Application Server uses separate classloaders for each application, thus ensuring that the old version is completely removed from the VM when a new one is deployed. Note that the Trifork Enterprise Application Server also supports automatic redeploy. This is further described in Section

111 Chapter 21. Deploying Archives Undeploying an Application The following command will undeploy an application: trifork archive undeploy <system name> <archive name without extension> <archive version> The Trifork Enterprise Application Server uses separate classloaders for each system container, thus ensuring that the application is completely removed from the VM when undeployed (actually the application is already removed in the classloader sense, when the system container is stopped) Hot Deploy The Trifork Enterprise Application Server supports Hot Deployment of J2EE archives. Hot Deploy refers to automatic deployment of archives dropped into a dedicated directory: Archives dropped into the trifork-do<main-dir>/servers/<server-name>/autodeploy directory are automatically deployed into the autodeploy system container. If the dropped archive is later updated, it is automatically redeployed. If an archive is removed from the autodeploy directory, it is automatically undeployed from the autodeploy system container. Hot Deploy can be a convenient way of quickly deploying an application into a Trifork Enterprise Application Server, without having to worry about environment setup and creating system containers Specifying the trifork-app-conf.xml It is possible to specify the trifork-app-conf.xml file to the deploy command. This way, it does not have to be included in the archive, and the archive will remain portable (although other servers will most likely just ignore trifork-app-conf.xml). Specify the trifork-app-conf.xml: trifork archive deploy -descriptor <name of trifork descriptor> <system name> <archive name> Inplace Deployment The Trifork Enterprise Application Server supports a special type of deployment, called Inplace Deployment. Normally, when an application is deployed, the server creates a copy of the application inside the server repository. This method is good for production environments as changes to the original source will not give unexpected changes in the application behavour. For development purposes, the situation is reversed: The developer wants the application to respond to source code changes as fast as possible. This is done in the Trifork Enterprise Application Server using Inplace deployment where the server will create a link from its repository to the application being deployed instead of creating a copy. Inplace deployment can be used for all types of J2EE applications (JAR, WAR, RAR and EAR files). trifork archive deploy -inplace <system name> <directory name> Inplace deployment is especially valuable in combination with inflated and mapped archives (see Section 19.1). Inplace deployment has multible avantages: The deployment process is faster, since the server doesn't have to copy the application. Changes to web applications (JSPs and static files) will show on the next HTTP request. Changes to Servlets, JavaBeans, EJBs and deployment descriptors requires a redeployment (same command as deploying inplace), but as no copying takes place, the reployment process will only take few seconds. 101

112 Chapter 21. Deploying Archives The application directory has to be accessible from the Trifork Enterprise Application Server, which means that the application files and the Trifork server have to be installed on the same physical computer Automatic Redeploy The Trifork Enterprise Application Server supports automatic redeploy of applications. This can be enabled for individual system containers (see Section 11.9). When automatic redeploy is enabled, the contents of inplace deployed archives is monitored for updates, and whenever an update is detected, the application is automatically redeployed Precompilation of JSP Files The trifork archive deploy command will, by default, compile all JSPs named in the web.xml file. This is a very nice feature as jsp compilation errors can be caught during deployment and not during test/production. To have your JSPs precompiled, just make sure that they are all named in the web.xml file: <web-app> <servlet> <servlet-name>welcome</servlet-name> <jsp-file>welcome.jsp</jsp-file> </servlet> </web-app> The precompiled JSPs are transferred to the server during deployment and stored in the server repository, to ensure fast first-time access to the JSPs. If you want to disable the JSP precompilation, specify the -nojspcompile option to the deploy command: trifork archive deploy -nojspcompile <system name> <archive name> Validation of XML Syntax The trifork archive deploy command will, by default, validate all deployment descriptors against their DTDs. This will ensure that the XML syntax is correct, and that the XML tags are properly named. If you want to disable the XML validation, specify the -noxmlvalidation option to the deploy command: trifork archive deploy -noxmlvalidation <system name> <archive name> Working with a Remote Server If the Trifork Enterprise Application Server is installed on remote server, you can still issue all the trifork commands on your local system. You just need to specify the -host option to tell where the Trifork server is located, e.g.: trifork realm -host <hostname> adduser <username> <password> Running a Web Client The Trifork Enterprise Application Server default binds web applications to port The context root is specified in the trifork-app-conf.xml file. Here is an example: <trifork-app-conf> <system-name>homebank</system-name> <web-app> 102

113 Chapter 21. Deploying Archives <context-root>/</context-root> </web-app> </trifork-app-conf> To access a web application deloyed with a context root of <blank> or "/", go to the URL: url> e.g. and to access the same file using a context root of "MyHomeBank": See Section for a description on setting up HTTP and HTTPS port numbers Deploying and Running J2EE Application Clients J2EE application clients are applications written in Java which need to access EJBs on the server. Application clients range from simple command line utilities that use standard I/O to highly interactive GUI applications using the Java Swing/AWT classes. The Trifork Enterprise Application Server has full support for J2EE application clients as specified in the J2EE specification. See Section 19.5 for a description of how application client should be packaged Deploying an Application Client Application clients are always packed in EAR files (see Section 19.7 for further information on how to do this), typically together with the EJB components that it is going to access. When an EAR file is deployed using the trifork archive deploy command, a number of client bundles (one for each archive) is generated. Client bundles are JAR files with a.tda extension. These contain the necessary files for the client application to run. The filenames of the client bundles will be the same as the application client module, except that the.jar extension will be replaced by.tda. By default the trifork archive deploy command will store the client bundles in the application servers repository. From there they can be started by using the clientlauncher tool (see Section ). In special cases you may choose to run the client using the trifork client run command (see Section for information on how to do this). In these cases you will need direct access to the client bundles. Use the -bundledir option with the trifork archive deploy command to specify a local directory to have the client bundle(s) stored into Running an Application Client Application clients are run in a client container, which is a server specific tool. In order to run an application client, the client container therefore needs to be present on the client machine. The Trifork Enterprise Application Server provides two ways of running application clients: Using the clientlauncher utility. When using this method the client container will automatically be downloaded to the client machine (using this method is recommended). Using the trifork client command. When using this method a client container needs to be installed manually on the client machine. In the following, these two different ways of running application clients will be described in detail. 103

114 Chapter 21. Deploying Archives Running an Application Client Using the Clientlauncher Tool The purpose of the clientlauncher utility is to make it simple for J2EE application developers to install, maintain and start application clients on multiple client machines. It does this by performing three tasks: Downloads the client container from the application server to the client machine. Each time the clientlauncher utility is started it checks if the application server has been upgraded. If this is the case is automatically downloads the new client container, and uses this to launch the application client. Downloads the application client bundle from the application server to the client machine. Each time the clientlauncher utility is started it checks if the application has been upgraded. If this is the case is automatically downloads the new client bundle, and launches this instead of the old one. Starts the application client using the client container and application client bundle which have been downloaded to the client machine. The only program you need to distribute to your client machines, is the clientlauncher utility itself. The clientlauncher can be found in the client-launcher directory of your Trifork Enterprise Application Server installation. The clientlauncher utility is started by the clientlauncher scripts, placed in the bin directory. Scripts are provided for Linux/Solaris (clientlauncher), Windows NT, 2000 and XP (clientlauncher.cmd) and Windows 98 (clientlauncher.bat). The clientlauncher utility provides the following options: -host - use this option to specify which host the Trifork Enterprise Application Server is running on. If only one application client is deployed on the host, this application client will be started automatically. If more than one application client is deployed on the host, a list of these will be presented along with information on which arguments to use with the following options in order to launch the application client. -http-port - use this option to specify which http-port on the host machine to connect to. If no port is specified, port 8080 will be used by default. -corba-port - use this option to specify which corba-port on the host machine to connect to. If no port is specified, port 2100 will be used by default. -system, -appname and -client - use these options to specify information on the system container the application client is deployed into, the application name used in the deployment and the name of the application client. It is not required that you specify all these options. If the options used are not enough to uniquely identify an application client, the clientlauncher utility will present information on which options and arguments you need to use in order to uniquely identify the application client. -no-gui - By default the clientlauncher utility will use a small GUI to show the status of downloads etc. If you for some reason do not want this GUI to be shown, use this option. A textual status representation will always be shown if you choose to run the clientlauncher from a command prompt. -vm-cmd - when the clientlauncher needs to spawn a new VM in order to start the application client it will use the javaw command on Windows and the java on Linux/Solaris from the standard path. If you need to change this behavior use this option to specify another VM (with full path) to use. Finally you can pass any number of arguments to your application client after the options to the clientlauncher utility Running an Application Client using the "trifork client" Tool If you choose not to use the clientlauncher utility, and instead use the trifork client command, you need to distribute the client container and application client bundle manually. Assuming that the EAR file containing the client application has been deployed using the trifork archive deploy command (and the -bundledir option), and the client container and application client bundle has been distributed to the client machine, the following command with start the client: 104

115 Chapter 21. Deploying Archives trifork client run <bundle name (.tda file)> <application arguments> Arguments after the bundle name are arguments to the client application Setting J2EE Application Client Properties For various reasons, some J2EE Application Clients may need one or more configuration properties. You can specify these in the <TRIFORK_DOMAIN_DIR>/client-config/client.properties file. When the Application Client is started, the properties from this file will be set as system properties, and you can therefore access them from your Application Client using System.getProperty("<your_property_name>") Please note that if you are running your Application Client using the clientlauncer tool described above, the client.properties will automatically be downloaded to your client machine, while you will have to make sure that the client.properties file is present if you choose to start your Application Client using the trifork client tool Transfering Additional Files Besides the Application Client properties, some Application Clients may need to have additional files transfered to the client machine (e.g., additional configuration files etc.). When using the clientlauncher tool, this can be accomplished by storing these files in the <TRIFORK_DOMAIN_DIR>/client-config/ directory. The clientlauncher tool will then make sure that these files are downloaded to and updated on the client machine Deploying and Running Clients Without Client Container It is possible with limitations to run an application client without using the Trifork client container, e.g., by using the java command to invoke a client main class directly. There are, however, some important features that are not available in this mode: CSI. The CSI protocol is not available. This means that the automatic transfer of login identity in bean invocations on the server is not available. java:comp. The java:comp environment is not set up for the application client, which means that the client application has to use the global JNDI namespace directly for locating beans and resources. User Transactions. There is no support for starting and controlling a transaction in the application client that spawns invocations in the server Generating RMI-IIOP Stubs The communication protocol supported for bean invocation by the Trifork Enterprise Application Server is RMI-IIOP. When using the Trifork client container this is transparent to the client application, but when running outside of the client container, it is necessary to explicitly create stubs for EJB remote and home interfaces, and to bundle these with the application client. IIOP stubs are generated by the trifork archive deploy command with the -iiop option is supplied: trifork archive deploy -iiop <name of Enterprise Archive> The above example will generate a JAR file called <name of Enterprise Archive>-iiop.jar. This file must be in the classpath of the VM used to invoke the application client together with the ejb classfiles, which can be downloaded at JavaSoft's website [ Connecting to the Trifork Enterprise Application Server From a Client 105

116 Chapter 21. Deploying Archives To connect to the Trifork Enterprise Application Server from a client using RMI-IIOP it is necessary to get an InitialContext from the server. com.sun.jndi.cosnaming.cnctxfactory is Sun's initial naming factory. The IIOP URL has the format iiop://<hostname>:<hostport>. These properties are either used as in the following example: // the code needed to get an InitialContext, using RMI-IIOP String iiopurl = "iiop://triforkserver:2121"; String contextfactory = "com.sun.jndi.cosnaming.cnctxfactory"; try { Properties props = new Properties(); props.put(context.initial_context_factory, contextfactory); props.put(context.provider_url, iiopurl); Context ctx = new InitialContext(props); } catch (NamingException ne) { ne.printstacktrace(); } or as parameters to the Java virtual machine: java -Djava.naming.factory.initial=com.sun.jndi.cosnaming.CNCtxFactory -Djava.naming.provider.url=iiop://<hostname>:<hostport> com.trifork.examples.helloworld 106

117 Part VII. The Trifork Assembly tool This guide describes how to use the Trifork Assembly Tool.

118 Chapter 22. Introduction This is the introduction to the Trifork Assembly Tool. The purpose of the Trifork Assembly Tool is to support assembly, configuration and deployment of J2EE applications for the Trifork Enterprise Application Server. The Trifork Assembly Tool supports the assembly of J2EE applications by constructing the J2EE archives in the required structure of.ear,.jar, and/or.war files. Configuration is performed through a graphical user interface which generats the deployment descriptors. Deployment to a running server is furthermore supported directly from the Trifork Assembly Tool. These features are described in further detail throughout the documentation. This chapter focuses on the basic layout and functionality of the Trifork Assembly Tool Starting the Trifork Assembly Tool The Trifork Assembly Tool is bundled with the Trifork Enterprise Application Server. To start the Trifork Assembly Tool use the trifork command from the command line: trifork assembly start The Trifork Assembly Tool can be started with different options. These options are: -workspace -project Workspace Layout The Trifork Assembly Tool is organized in workspaces where all work with J2EE applications is performed. The layout of the workspace can be seen in Figure 22.1 Figure The Trifork Assembly Tool workspace The workspace consists of a series of areas. These areas are: 108

119 Chapter 22. Introduction Main Menu Toolbar Tree View serversprojects Work Area Error and Warning Area Tool Log Infobar Main Menu The main menu is placed at the top of the workspace: Figure The main menu The menu consists of: File Project Archive Server View Tools work area Window Help Toolbar The toolbar is placed just below the main menu. Figure The toolbar The functionalities of the icons in the toolbar are: Tree View 109

120 Chapter 22. Introduction The tree view is placed at the left side of the workspace. From the root it has two main nodes; a servers node that contains all available (mounted) servers, and a projects node that contains all open projects. Figure Servers and projects in the tree view Each server node can be expanded, showing informations about the principals, endpoints, EJBs, resources, and systems existing in the server: Figure A server in the tree view Each project appearing in projects node may be expanded to reveal its archives. Archives may be expanded to list nested archives and components: Figure A project in the tree view 110

121 Chapter 22. Introduction Different types of archives and components have different functionality available. This functionality can be accessed by the popup menu of the given node. The functionality attached to the different types of archives and components is discussed further in this section Common Functionality of Popup Menus Some functionality is available among several types of nodes. The functionality is described in this section. The functionality is accessed by right clicking nodes in the tree view. This will open popup menus containing the functionality of interest: Save Save as... Save descriptors Set URL Encoding Description Move up Move down Deploy work area Inspect View descriptors Delete Close Enterprise Archive The available enterprise archive specific functionality of an enterprise archive's popup menu is described in this section. Figure Popup menu for a enterprise archive 111

122 Chapter 22. Introduction ejb jarweb archiveapp client New addnew Add Add as archive EJB JAR Archive The available EJB JAR specific functionality of an EJB JAR's popup menu is described in this section. Figure Popup menu for a EJB JAR archive 112

123 Chapter 22. Introduction Add files.class Activate bean Move out CMR Web Archive The available web archive specific functionality of a web archive's popup menu is described in this section. Figure Popup menu for a web archive 113

124 Chapter 22. Introduction Add files Activate web component Move out Application Client The available application client specific functionality of an application client's popup menu is described in this section. Figure Popup menu for an application client 114

125 Chapter 22. Introduction Add files.class Enterprise JavaBean The entreprise JavaBean does not have any unique functionality. See Section for a description of the general functionality. Figure Popup menu for an EJB 115

126 Chapter 22. Introduction Java Server Page The available JSP specific functionality of a java server page's popup menu is described in this section. Figure Popup menu for a JSP <varlistentry>copymakes a copy of this web component, which can be configured independently of the original web component.</varlistentry> Servlet The functionality available to a servlet's popup menu equals the functionality of a java server page. Java server pages are compiled to servlets internally by the Trifork Enterprise Application Server, hence the similarity. Refer to the description of java server page for more information. 116

127 Chapter 22. Introduction Error and Warning Area The error and warning area is placed below the tree view in the workspace. In this area unresolved errors and warnings of the selected tree node are shown. For instance, if an enterprise java bean (named TempConverterBean in this example) does not define a jndiname, the error and warning area will show the following error: Error: Bean "TempConverterBean": jndi-name not set. The error will also be visible in the tree view where the path from the projects node to the node containing the error is colored red. Figure Errors are indicated in the tree view Clicking a statement in the error and warning window will open an inspection window in the work area for the component where the error originates. As with errors, warnings are also highlighted in the tree view. The path from the projects node to the node containing the warning is colored yellow in this case. Warnings are accompanied by a check box in the error and warning area. Marking a warning as checked will remove (ignore) it. The default display of errors and warnings can be changed from either the main menu under view or in the toolbar Tool Log The tool log is placed below the work area, and it will show information from the Trifork Assembly Tool. The information in this area can be used to see which tasks the Trifork Assembly Tool has performed. The log is supposed to be informative but not essential for working with the tool - important errors and warnings about the project are shown in the error and warning area Infobar The infobar is placed in the bottom. This bar shows a few things: the selected project, the selected node in the tree view, the number of unresolved errors and warnings and the current system date and time. 117

128 Chapter 23. Assembling a Simple J2EE Application This example shows how to assemble a simple J2EE application. The sample application is a temperature converter supporting conversion of temperatures from celcius to fahrenheit. The components used in the application are; (a) a stateless session bean (TempConverter) containing the conversion logic, (b) a java server page (TempConverter.jsp) complementing the display layer, and (c) a javabean wrapper (TempConverterWrapper) used for accessing the TempConverter enterprise java bean from the java server page. The source code of the components used in the application is available in samples directory of the server installation Creating the Basic Structure First a new project must be created. Creating a project can be done by right-clicking the projects node. Figure Creating a new project Select new and enter the project name in the dialog box that appears, e.g. sample. Storage location of the project may be changed, if necessary, by pressing the Change... button. When the entered information is corect, press OK. A new project node is added to the projects node. Next, a new enterprise archive must be added to the project. This is done by right-clicking the project node. Figure Creating an enterprise application archive 118

129 Chapter 23. Assembling a Simple J2EE Application From the popup menu, select New->Enterprise archive and enter a name for the enterprise archive to be created, e.g. sample. This will create an enterprise archive where two new archives must be added, an ejb jar and a web archive: Figure Creating a new archive inside a enterprise application archive 119

130 Chapter 23. Assembling a Simple J2EE Application An EJB JAR is created by clicking New->Ejb jar. Name this archive sample. Likewise a web archive is generated by clicking New->Web archive. Also name this archive sample. The archive name will be extended respectively with.jar and.war by the Trifork Assembly Tool. After adding the two archives, the structure should look like this: Figure The structure of the enterprise application archive after an EJB JAR and a web archive has been added 120

131 Chapter 23. Assembling a Simple J2EE Application Adding an Enterprise Java Bean The basic structure of the enterprise archive is now prepared and the TempConverter enterprise java bean is ready to be added. The TempConverter enterprise java bean is added to the EJB JAR by right-clicking the sample.jar node in the treeview: Figure Adding an EJB to an EJB JAR archive 121

132 Chapter 23. Assembling a Simple J2EE Application Click Add files and select the class files for the TempConverter enterprise java bean. These files can be found in <TRIFORK_INSTALL_DIR>/examples/stateless/src/sample.ear/sample.jar During the addition of the files, the Trifork Assembly Tool will detect that the class files belong to a specific package and can be moved into the right directory structure in the project. Figure Automatic generation of packages 122

133 Chapter 23. Assembling a Simple J2EE Application Just press the OK button. Now the files are placed correctly in the EJB JAR archive. Next, the Trifork Assembly Tool will detect that one of the class files represents an enterprise java bean and ask if the TempConverterBean should be added to the model Figure Detection of EJBs Answer Yes to this question. Answering No just adds the files to the archive, but does not interpret them as an enterprise java bean. Now the enterprise java bean is represented by a node in the EJB JAR with the name TempConverterBean Figure Inspection of an EJB 123

134 Chapter 23. Assembling a Simple J2EE Application The TempConverterBean has not yet been configured, so the sample.ear is not deployable at this time. This is shown by the Trifork Assembly Tool by coloring the path from the projects root node to the TempConverterBean node red. The actual error is shown in the error and warning area. In this case, the jndi name of the TempConverterBean is not configured. Figure Error in an EJB 124

135 Chapter 23. Assembling a Simple J2EE Application The jndi name is configured by right-clicking the TempConverterBean node and clicking Inspect or by doubleclicking the error message in the error and warning area. Either way, an inspect window is opened in the work area (as already shown further above). Here the enterprise java bean can be configured. In the inspect window under General->JNDI name the jndi name must be set to ejb/tempconverter. This resolves the error, and makes the sample.ear deployable Adding the Web Components The EJB JAR is now ready, and the web archive must be assembled. The TempConverter.jsp and the TempConverterWrapper must be added to the web archive. First the java server page (TempConverter.jsp) is added. This is done by right-clicking the sample.war node in the tree view which brings up a popup menu: Figure Adding web components to a web archive Click Add files and select the TempConverter.jsp in /exam<trifork_install_dir>ples/stateless/src/sample.ear/sample.war/tempconverter.jsp. During the addition, 125

136 Chapter 23. Assembling a Simple J2EE Application the Trifork Assembly Tool detects that the added file looks like a web component, and asks if it should be added to the model. Figure Autodetection of web components Answer Yes, to the question. Figure A JSP has been added to the web archive After the TempConverter.jsp has been added, it is shown as a node in the sample.war node. Now inspect the java server page. Figure Inspecting a JSP file 126

137 Chapter 23. Assembling a Simple J2EE Application Configure the Servlet mapping as /TempConverter, which makes the TempConverter.jsp available as TempConverter. Now inspect the sample.war to configure the web archive by selecting Inspect from its popup menu. Figure Inspecting a web archive 127

138 Chapter 23. Assembling a Simple J2EE Application In the inspect window the context root can be configured under Details->Context Root. Set the context root to / sample. Now, thetempconverterwrapper and the TempConverterBean home and remote interfaces must be added to the sample.war archive. These components are added from the Inspect tab in the web applications inspect window, by right-clicking the classes node: Figure

139 Chapter 23. Assembling a Simple J2EE Application Select Add files and select TempConverterWrapper.class from the sample. Now the TempConverterWrapper has been added. Next, click Add files again and select the TempConverter.class and TempConverterHome.class. This will add the remote and home interface respectively. During the addition of the files, the Trifork Assembly Tool will detect that the.class files belong to a specific package and will suggest it moved into the equivalent directory structure. Answer Yes to this question. After adding all files, the tree view in the inspect window should look like this: Figure Adding files to a web archive 129

140 Chapter 23. Assembling a Simple J2EE Application This completes the assembly of the sample.war and the sample.ear is now ready to be deployed to the Trifork Enterprise Application Server Adding a Server The sample.ear enterprise archive is assembled and ready to be deployed to a Trifork Enterprise Application Server. To deploy the enterprise archive, a server instance must be added to the Trifork Assembly Tool. To add a server, right-click the Servers node in the tree view: Figure Adding a server 130

141 Chapter 23. Assembling a Simple J2EE Application Click Add server, and a dialog will open. Here the server parameters can be entered. In this example, a server named ptoserver from the ptodomain is added. The default login (administrator) and password (trifork) for the Trifork Enterprise Application Server is used as well: Figure Configuration of server parameters Press OK, and the Trifork Assembly Tool will connect to the server and retrieve information about the server instance. When a server instance has been added, a server node will appear in the tree view. If the server is not running it will be marked as offline. A server must be online in order to deploy to it. 131

142 Chapter 23. Assembling a Simple J2EE Application Figure An added server Now, the application can be deployed to the server Deploying an Application An application (sample.ear) has been assembled and a server instance (ptodomain:ptoserver) has been added. The application can now be deployed to the server. This is done by selecting Deploy from the applications, i.e. the sample.ear popup menu. Figure Popup menu for an enterprise application archive 132

143 Chapter 23. Assembling a Simple J2EE Application Enter a system name (name of a system container) in the dialog that appears, eg. sample and press OK. Figure Deploying an application 133

144 Chapter 23. Assembling a Simple J2EE Application The Trifork Assembly Tool will pop up a dialog stating that the system (sample) has not yet been created and ask if this system should be created. Figure Creating a system container Answer Yes to this question. The Trifork Assembly Tool will now create this system and continue deployment of the application Running the Application The sample application is now deployed to the Trifork Enterprise Application Server and can be accessed at Figure The running application 134

145 Chapter 23. Assembling a Simple J2EE Application 135

146 Chapter 24. Component Management This chapter describes the management of components in the Trifork Assembly Tool. The components of interest are enterprise archives, EJB JAR archives, web archives, enterprise java beans, and web components (servlets and java server pages) Enterprise Archives An enterprise archive is a stand alone archive. Basically it encapsulates other archives, hence the enterprise archive only provides a limited set of functionality. To configure an enterprise archive, select Inspect from an enterprise archives popup menu. This will open a window for inspection in the work area, where configuration can be performed. Figure Inspecting an enterprise archive The inspect window for an enterprise archive consists of two tabs; Inspect and Classpath Inspect From the Inspect tab archives can be created, added, and removed from the enterprise archive. Creation and addition are performed by right clicking the enterprise archive node (here sample.ear). Removal is performed by right-clicking an archive located in the enterprise archive (here sample.jar or sample.war). 136

147 Chapter 24. Component Management Classpath The classpath can be changed in the Classpath tab. The classpath settings given here are stored in the METAINF/MANIFEST.MF file in the enterprise archive. Initially, the classpath is empty EJB JAR archives An EJB JAR archive is a JAR file of enterprise java beans. The EJB JAR archive can be a part of an enterprise archive or a stand alone archive. To configure an EJB JAR archive, select Inspect from an EJB JAR's popup menu. This will open a inspection window, in the work area where configuration can be performed. Figure Inspecting an EJB JAR archive The inspect window for EJB JAR archives consists of three tabs; Inspect, Classpath and Principals Inspect In the Inspect tab, files can be added and removed. 137

148 Chapter 24. Component Management Classpath The Classpath tab makes it possible to change the classpath. The settings are stored in the METAINF/MANIFEST.MF file in the EJB JAR archive. Initially, the classpath is empty Principals In the Principals tab it is possible to specify roles (i.e. security settings) for the EJB JAR archive. Roles can be added and removed and principals for a given role can be specified. Figure Configuration of principals it is possible to use both existing principals or create new ones. An existing principal may be dragged from a server node in the tree view to the right column principal list in the inspection window. The security settings for a role can be specified by pressing the Edit security button which will bring up a new dialog: Figure Configuration of security settings 138

149 Chapter 24. Component Management From the Security settings dialog the security settings for each enterprise java bean can be configured. It is possible to configure allowed methods for a each role along with run-as settings and the use of security-role-refs Web archives A web archive is a JAR file of web components. The web archive can be a part of an enterprise archive or a stand alone archive that can be deployed independently. To configure a web archive, select Inspect from a web applications popup menu. This will open a inspection window, in the work area where configuration can be performed. Figure Inspecting a web application 139

150 Chapter 24. Component Management The inspect window consists of eight tabs; Details, Inspect, Listeners, Java:comp, Context param, Mime map, Roles/Principals and Security Details The Details tab contains the following configurations: Context root Session timeout Welcome files index.html Endpoints Inspect 140

151 Chapter 24. Component Management In the Inspect tab, files can be added to and removed from the archive Listeners From the Listeners tab, it is possible to add and remove application listeners to and from the web archive respectively. Application listeners are classes that implement one or more of the servlet event listener interfaces. The servlet event listener interfaces support event notifications for state changes in the ServletContext and HttpSession objects Java:comp The Java:comp tab contains configuration of the following entries: ejb refs, resource refs, resource env refs and env entries. These entries can be added, edited and removed Context Params The Context param tab contains the declaration of the web archive's servlet context initialization parameters. Parameters can be added, edited and removed Mime mapping In the Mime mapping tab, mappings between extensions and mime types can be specified. Mappings can be added, edited and removed Roles/Principals From the Roles/Principals tab, it is possible to specify at set of roles for the web archive. Roles can be added and removed and principals for the roles can be specified. Principals can either be created or principals already specified in a server can be used. Using an principal specified in a server is done by drag-and-drop. A principal can be dragged from a server node in the tree view to the right column principal list in the inspection window. Figure Role/principal configuration 141

152 Chapter 24. Component Management Security The Security tab contains configuration for the security of the web archive. The options in the Security tab are: Auth method BASICDIGESTFORMCLIENT-CERT Realm name Form login formauth method page Form errormethod formauth page Security constrains 142

153 Chapter 24. Component Management Figure Configuring security constraints Enterprise java beans Enterprise java beans can be devided into three types: entity beans, session beans or message driven beans. The configuration for these types differ slightly. To configure an enterprise java bean, right-click on the node in the tree view and select Inspect. This will open a window for inspection, in the work area, where configuration can be performed. The inspect window of a session bean consists of five tabs; General, Interfaces, Details, Java:comp and Transaction settings. The entity bean has an extra tab; Persistence General The General tab contains the following configurations: Ejb name Ejb class Browse Reentrant Session type StatefulStateless Transaction type beancontainer 143

154 Chapter 24. Component Management JNDI name Interfaces At the Interfaces tab, its possible to specify the classes that represent the EJB class, the Home interface, the Remote interface, the Local home interface and the Local interface. The selectable classes for a given interface, are limited to the loaded classes of the correct form. As an example, the selectable home interfaces for an enterprise java bean are only those classes that have the form of a home interface, ie. classes that extends javax.ejb.ejbhome. The Browse button attached to each choice list may be used to select among all loaded classes regardless of their form Details The Details tab contains the following configurations: Description Max pool size Default pool size Idle timeout Java:comp The Java:comp tab contains configuration of ejb refs, resource refs, resource env refs and env entries. These entries can be added, edited, and removed Transaction settings The Transaction settings tab represents the transaction attributes of the enterprise java bean. For each method in the bean the transaction attributes can be set Persistence The Persistence tab is only available for entity beans. It contains the configuration for how to persist entity beans into a database. Figure Configuring persistence 144

155 Chapter 24. Component Management The Persistence tab contains the following configurations: Persistence type containerbeanpersistence CMP version 1.x2.x Advanced EJB QLDbCMP layoutejb QLhereDb layouthere Primary key class Browse CMP fields Primary key field 145

156 Chapter 24. Component Management Abstract schema name EJB QL The EJB QL dialog can be opened from the persistence tab and it supports configuration of find- and select methods declared by the entity beans. Figure Specifying find and ejbselect methods Each find- and select method can be associated with a query specified in EJB QL. In the example show above, the findall method is associated with the query SELECT OBJECT(o) FROM SimpleEntityBean AS o. The schema name used in the query (SimpleEntityBean), is the abstract schema name specified in the Persistence tab Db Layout The Table layout dialog can be opened from the persistence tab. The Table layout supports management of tables to be used for persistence of entity beans. 146

157 Chapter 24. Component Management Figure Configuring table layout The Table layout dialog consists of the following configurations: Table name TablelayoutCMP table layout fieldpersistencetable layout Table life cycle JNDI name Principal Password Web Components 147

158 Chapter 24. Component Management Web components, i.e. servlets and jsps, can be configured using the Trifork Assembly Tool. The configuration of a servlet is similar to the configuration of a java server page. Java server pages are compiled to servlets internally by the Trifork Enterprise Application Server, hence the similarity. Since the configuration of servlets and java server pages are similar, they are described together in this section. To configure a web component, right-click on a servlet or java server page component in the tree view and select Inspect. This will open a window for inspection, in the work area where configuration can be performed. The inspect window of web components consists of three tabs; General, Init param and Security General The General tab contains the following configurations: Servlet name JSP File name File name jspbrowsejsp Servlet class class BrowseServlet Servlet mapping Load on startup Startup sequence YesSeq.# Init param From the Init param tab, initialisation params from web components can be added, edited and removed Security In the Security tab, security role can be added, edited and removed. The security roles are used in the security constraints placed on the web archive. The role name is the role name to a security role ref. The role link are roles that can be configured in the web archive regarding security constrains Deployment Descriptors The three types of archives (enterprise archive, ejb jar archive and war archive) have deployment descriptors attached. Four types of deployment descriptors are used: enterprise archive trifork-app-conf.xml application.xml ejb jar archives ejb-jar.xml web archives web.xml Deployment descriptors are generated by the Trifork Assembly Tool based on the configuration of the components performed in the Trifork Assembly Tool. Deployment descriptors can be viewed by right-clicking any archive and select View descriptor(s). Open deployment descriptors are always equivivalent with the specification set in the Trifork Assembly Tool and changes made from the tool are immediately reflected in the deployment descriptors. 148

159 Chapter 25. Server Management This chapter describes the server management available in the Trifork Assembly Tool. Here servers can be added and imported to the tool - making servers available for creating system containers and deploying J2EE applications Adding a Server A Trifork Enterprise Application Server may be added to the Trifork Assembly Tool which will mount the server and make it available for performing operations on the server directly from the Trifork Assembly Tool. To add a server, right-click the Servers node and select add server This will bring up a dialog where server parameters can be specified: Figure Configuring server parameters Specify the Domain name, Server name, Address and Port of the server to add. The Login and Password are optional. By omitting the Login and Password, you will be prompted for these informations first time an operation is performed on the server. The Login and Password may also be set later, this is described further in the general server management. When the server parameters have been entered, click OK. Now the Trifork Assembly Tool will be connecting to the server Connecting to a Server 149

160 Chapter 25. Server Management Connecting to the server may be performed in two ways; (a) explicitly requested by the user by pressing Connect on a offline server node or (b) automatically by the Trifork Assembly Tool during Add server or Import Server operations. The connection state of a server is denounced in the server node's label. The state may be either: connecting, online or offline. While the Trifork Assembly Tool is connecting to a server the state is connecting: Figure Connecting state When a connection to the server has been established the server will change state to online: Figure Online state If a connection to the server cannot be established, the server will change state to offline: Figure Offline state A server in state offline can have the server parameters respecified, and establishment of new connections may be attempted General Server Management The Trifork Assembly Tool supports a limited set of functionalities for server management. The available functions can be accessed by right-clicking a server node in the tree view. 150

161 Chapter 25. Server Management Figure General server management The functionality available to a given node depends on the state of the server. It is e.g. only possible to login on an online server instance. Remove Connect LoginPassword Login Set servernameserver Domain params nameaddressportloginpassword Reload New system Server nodes may be expanded/collapsed like other nodes in the tree view. Expanding a server node will reveal principals, endpoints, ejbs, resources and systems available at the server. Figure Contents of a server 151

162 Chapter 25. Server Management The information about principals, endpoints, ejbs, and resources may be used during the assembly of J2EE archives. 152

163 Part VIII. Trifork tools This guide contains detailed information on the trifork command line tools as well as the trifork ant integration.

164 Chapter 26. The Trifork command line tools The trifork command line tools are divided into a number of command groups. Each command group contains one or more subcommands. All the subcommands are described in detail in this chapter archive trifork archive convert NAME archive convert SYNOPSIS trifork archive convert [options] <archive> DESCRIPTION To run a J2EE application it needs to first be assembled in an archive which includes the relevant deployment descriptors that describe the structure of the components included in the archive. If such an archive has deployment descriptors fitting another server, and you want to deploy it to the trifork server, the deployment descriptors has to be converted to the right format. The trifork archive convert command converts third party archives to trifork compatible archives. The current available converters are: Weblogic 5.1 converter Sun Reference Implementation 1.3 converter ARGUMENTS archive Specify the archive to be converted OPTIONS -define -D <key=value> -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print short help -man 154

165 Chapter 26. The Trifork command line tools Print long help. -overwrite Force overwrite trifork-system-conf.xml. If a legacy xml-file exists, the deployment of the archive can have unforseen consequences. DEFAULT is no overwrite -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork archive convert myarchive This command converts the deployment descriptors in the archive myarchive to the right format for the trifork server trifork archive deploy NAME archive deploy SYNOPSIS trifork archive deploy [options] <system-name> <archive> <directory> DESCRIPTION To run a J2EE application it needs to first be assembled in an archive which includes the deployment descriptors that describe the structure of the components included in the archive. Next, the application needs to be "uploaded" to the server; verifying consistency of the application. This uploading/install is referred to as deploying the application. An Enterprise archive (ear) consists of modules of three different types. It is not required that modules of all three types are present in the archive. The enterprise archive may furthermore contain any number of modules of each type. Web modules, placed in.war files Enterprise Java Beans, placed in.jar files Application clients, placed in.jar files These archives are are bundled together in the enterprise archive, which simply is a jar archive with an.ear extension. A file created with the Java jar utility bundles the files in a directory into a single Java ARchive (JAR) file, maintaining the directory structure. The Java classloader can search for Java class files (and other file types) in a JAR file the same way that it searches a directory in its classpath. Because the classloader can search a directory or a JAR file, you can deploy J2EE components on Trifork Server in either an "exploded" directory or a JAR 155

166 Chapter 26. The Trifork command line tools file. The trifork archive deploy command deploys an application to the server. A system has to be created first, in order to specify which system to deploy the archive to. This command requires a running server! ARGUMENTS system-name archive Specify the name of the system to deploy the archive to. Specify the name of archive to deploy. system-name Specify the directory containing the files to be deployed, if these are not bundled together in an archive OPTIONS -noactivation The deployed version is not activated. DEFAULT is activation. -appname <application-name> Specify application name. DEFAULT is the application assembled in the archive. -bundledir <bundle-dir> Specify a local directory to have the generated client bundless stored into. By default the trifork archive deploy command will store the client bundles in the application servers repository. From there they can be started by using the clientlauncher tool. In special cases you may choose to run the client using the trifork client run command. In these cases you will need direct access to the client bundles. DEFAULT is storing in the application servers repository. -define -D <key=value> Specify java properties to be delegated to the virtual machine. This option can be used multiple times. 156

167 Chapter 26. The Trifork command line tools -descriptor <descriptor> Supply the trifork-system-conf.xml descriptor. For each component type, the deployment specifications define the files required and their location in the directory structure. The Trifork server requires an additional trifork-system-conf.xml file. This way, it does not have to be included in the archive, and the archive will remain portable. DEFAULT is the trifork-system-conf.xml file included in the application package. -help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -iiop Generate iiop stubs for CORBA clients. DEFAULT is no generation. -inplace The developer want the application to respond to source code changes as fast as possible. The server will create a link from its repository to the application being deployed instead of creating a copy. Thus making the deployment process a lot faster. Using this option a directory instead of an archive should be specified in the command line. This gives a great advantage during development, as applications being developed doesn't have to be packed each time a redeployment is needed. DEFAULT is copying. -nojspcompile Disable precompilation of JSPs. DEFAULT is precompilation. By doing this, all compilation errors are catched during deployment. To have your JSPs precompiled, just make sure that they are all named in the web.xml file. -man Print short help Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. 157

168 Chapter 26. The Trifork command line tools -norestart Do not restart system container. DEFAULT is restart -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -type web ejb ear rar client Specify which type of archive to deploy. This overrides the guessing procedure based on extensions. DEFAULT is using a guessing procedure based on extensions. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -version <application-version> Specify application version. DEFAULT is the current version of the application. -vmargs <key=value> DEFAULT is the server found in the environment variable. For other parameters that you may want to control, such as heap and stack size. -noxmlvalidation Disable DTD validation of XML descriptors. DEFAULT is validation EXAMPLE trifork archive deploy mysystem myarchive 158

169 Chapter 26. The Trifork command line tools This command deploys the archive myarchive to the system mysystem. trifork archive deploy -type client mysystem mydirectory This command deploys the archive found in mydirectory to the system mysystem. The archive to be deployed is of type client trifork archive undeploy NAME archive undeploy SYNOPSIS trifork archive undeploy [options] < system-name > < app-name > < app-version > DESCRIPTION To run a J2EE application it needs to first be assembled in an archive which includes the deployment descriptors that describe the structure of the components included in the archive. Next, the application needs to be "uploaded" to the server; verifying consistency of the application. This uploading/install is referred to as deploying the application. The trifork archive deploy command deploys an application to the server. A system has to be created first, in order to specify which system to deploy the archive to. The trifork archive undeploy command undeploys a deployed application. This command requires a running server! ARGUMENTS system-name app-name Specify the name of the system the application should be undeployed from. Specify the name of application to undeploy. app-version Specify the version of the application to be undeployed OPTIONS -help Print short help -host <host> 159

170 Chapter 26. The Trifork command line tools If the server runs on a remote host, specify the host. DEFAULT is localhost. -man Print long help. -norestart Do not restart system container. DEFAULT is restart -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork archive undeploy petstore_container petstore.ear 1 This command undeploys the application with name petstore.ear and versionnumber assembly trifork assembly start NAME 160

171 Chapter 26. The Trifork command line tools assembly start SYNOPSIS trifork assembly start [options] DESCRIPTION To run a J2EE application it needs to first be assembled in an archive which includes the relevant deployment descriptors that describe the structure of the components included in the archive. Next, the application needs to be "uploaded" to the server; verifying consistency of the component/application. This uploading/install is referred to as deploying the application and is done with the trifork archive deploy command. Deployment descriptors (XML files describing the components in an archive) play an important role in J2EE, and they have a number of different uses in an application server, most importantly for describing the structure of archives. Another important use is to describe a J2EE component's requirement to it's environment, and how to fulfill these requirements. When the application has been properly packaged, its time to create a Trifork server specific deployment descriptor, called trifork-system-conf.xml. This file contains server specific deployment information, like: Binding information (for <ejb-ref> and <resource-ref>) Web application setup (context-root and port numbers) Security setup (role mappings) Applications have deployment descriptors that describe the contents of the directory or archive file. Deployment descriptors are XML documents. The J2EE specifications define standard, portable deployment descriptors for J2EE applications. Trifork defines additional Trifork-specific deployment descriptor required to deploy an application to the Trifork Enterprise Application Server. The purpose with the assembly tool is to generate the right deployment descriptors for the archives to be deployed. In order to make a logical division of the archives they can be included in different projects. The trifork assembly start command starts the assembly tool OPTIONS -define -D <key=value> -help Print short help. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -project <project> Specify a project to be included in the assembly tool, when it starts. 161

172 Chapter 26. The Trifork command line tools -vmargs <key=value> DEFAULT is no project. For other parameters that you may want to control, such as heap and stack size. -workspace <workspace> Specify the workspace to be used in the assembly tool, with the properties for the GUI and the directories to search in for archives. DEFAULT is the workspace default.tws found in the tmp directory EXAMPLE trifork assembly start This command starts the assembly tool with the default workspace settings and no projects auth trifork auth login NAME auth login SYNOPSIS trifork auth login [options] DESCRIPTION The tools used for tasks such as deploying an application, creating a user, stopping the server etc. will ask for username and password as required. In development situations this can become a hazel. As an alternative you can use the trifork auth login command to make a permanent login on the server, thus eliminating the need for making a login each time you use the commands. By issuing the trifork auth login command a file named '.triforklogin' will be created in your home directory. This file contains an encrypted version of the specified username and password. The server will subsequently use the username and password from this file when needed. Please make sure that this file is kept private since, if distributed, it can be used as a management key to you server. This command requires a running server! OPTIONS -define -D <key=value> Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -host <host> 162

173 Chapter 26. The Trifork command line tools If the server runs on a remote host, specify the host. DEFAULT is localhost. -help -man Print short help Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork auth login This command will prompt the user for username and password trifork auth logout NAME auth logout SYNOPSIS trifork auth logout [options] DESCRIPTION The trifork auth logout command logs a user out. See the description of the trifork auth login command for how to log in. 163

174 Chapter 26. The Trifork command line tools OPTIONS -define -D <key=value> -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Print short help -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork auth logout This command will prompt the user for username client trifork client listclients NAME client listclients SYNOPSIS trifork client listclients [options] DESCRIPTION By issuing this command a list of the applications clients currently connected to the server will be shown. By default the command will just show the names of the machines the clients are running on. It is however possible to extend this information by implementing certain features in the application client. How this is done is described in detail in the user documentation. This command requires a running server! OPTIONS 164

175 Chapter 26. The Trifork command line tools -define -D <key=value> -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Print short help -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork client listclients trifork client publishmessage NAME client publishmessage SYNOPSIS trifork client publishmessage [options] <subject> DESCRIPTION This command makes it possible to publish messages to application clients connected to the server. The message is specified as a subject and an optional body. By default the message will be published to all connected clients. When using the -receivers option it is possible to specify a single or a comma separated list of client to publish to. Use the trifork client listclients command to get a list of connected clients. In order for the application client to handle the published messages, some code is needed in the application client. Please referee to the user documentation for details on this. This command requires a running server! ARGUMENTS 165

176 Chapter 26. The Trifork command line tools subject Specify the subject of the message to publish OPTIONS -receivers <message-receivers> -body <message-body> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Print short help -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -host <host> Specify the body of the message to publish -define -D <key=value> Specify a single or a comma separated list of client name to stop Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork client publishmessage -body "The server will be upgraded in 15 minutes..." "Important message" trifork client run NAME client run 166

177 Chapter 26. The Trifork command line tools SYNOPSIS trifork client run [options] <client-bundle> [client-args] DESCRIPTION J2EE application clients are applications written in Java which need to access EJBs on the server. Application clients range from simple command line utilities that use standard I/O to highly interactive GUI applications using the Java Swing/AWT classes. Application clients are always packed in EAR files, typically together with the EJB components that it is going to access. When an EAR file is deployed using the trifork archive deploy command, the EAS tool will automatically generate a number of client bundles (one for each client). Client bundles are jar files with a.tda extension. These contains the necessary files for the client application to run. The filenames of the client bundles will be the same as the application client module, except that the.jar extension will be replaced by.tda. Application clients are run in a client container, which is a server specific tool. The Trifork Application Server also provides the clientlauncher utility. This makes it simple for J2EE application developers to install, maintain and start application clients on multiple client machines, by automatically updating the application client. The clientlauncher facility is described in detail in the user documentation. The trifork client run command starts the client ARGUMENTS client-bundle Specify the client bundle for the client to be run OPTIONS -noallowexit Client application is not allowed to call exit at end of main. DEFAULT is to allow to call exit at end of main. -define -D <key=value> Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -noexit Client container does not call System.exit at end of main. DEFAULT is call of exit at end of main. -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. 167

178 Chapter 26. The Trifork command line tools -help -log <category:level> Set log level for log category. The category name should be based on the class name of the component doing the logging. It contains the necessary methods for logging various levels of messages. The set of possible log levels are: debug, info, warn, error and fatal. This option can be used multiple times. DEFAULT is the log levels described in [TRIFORK_DOMAIN_DIR]client-config/log4j-client.xml the configuration file at / -man Print short help Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork client run -log com.trifork.eas:debug -noexit myclientbundle trifork client run -host myhost -define key1=value1 -define key2=value2 mysecondclientbundle trifork client stopclients NAME client stopclients SYNOPSIS trifork client stopclients [options] DESCRIPTION This command makes it possible to stop applications clients running on client machines. By default it will signal all connected client to stop. When using the -receivers option it is possible to specify a single or a comma separated list of client names to stop. Use the trifork client listclients command to get a list of connected clients. This command requires a running server! OPTIONS -receivers <message-receivers> Specify a single or a comma separated list of client name to stop 168

179 Chapter 26. The Trifork command line tools -define -D <key=value> -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Print short help -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork client stopclients -receivers client1,client2,client compile trifork compile jspc NAME compile jspc SYNOPSIS trifork compile jspc [options] <inputfile> DESCRIPTION The trifork compiler jspc command is a JSP compiler. It make it possible to compile JSP file and return the result in a number of formats (XML, Java or Class files). This could e.g. be used to statically check your JSP files before deploying them to the server ARGUMENTS inputfile Specify the JSP file to compile 169

180 Chapter 26. The Trifork command line tools OPTIONS -classpath <classpath> -define -D <key=value> Specify input type to either xml or jsp By default the inputtype is extracted from the prefix of the JSP file -man Use this option to have the output from the compile on stdout instead of in a file -stage java xml class Specify whether the compiler should produce a XML file, a Java file or a class file DEFAULT is java -vmargs <key=value> Use this option to specify the name of the output file -pipe Print long help. -output <file-name> Print short help -inputtype xml jsp Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -help Specify the classpath to be used when compiling the JSP file For other parameters that you may want to control, such as heap and stack size. -war <war-dir> <war-file> 170

181 Chapter 26. The Trifork command line tools Specify a WAR archive in which to look for included JSP files EXAMPLE trifork compile jspc -output MyJSPFile.class -stage class myjsp.jsp domain trifork domain create NAME domain create SYNOPSIS trifork domain create [options] <base-dir> <domain-name> <server-name> DESCRIPTION To start the server, a domain has to be created, since all servers must belong to a domain. The trifork domain create command creates a domain with the chosen name in the chosen directory with the chosen server. When the domain is created, a script trifork, is created in the $TRIFORK_DOMAIN_DIR. The script contains the configuration for running the server in this domain ARGUMENTS base-dir domain-name Specify the directory to save the domain in. Specify the domain name. server-name Specify the server name OPTIONS -define -D <key=value> Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -help 171

182 Chapter 26. The Trifork command line tools -man Print short help Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork domain create mydomaindir mydomainname myservername trifork domain export NAME domain export SYNOPSIS trifork domain export [options] <domain-name> DESCRIPTION This command prints the configuration files for the servers in a domain to a chosen file or console in xml ARGUMENTS domain-name Specify the domain name OPTIONS -file <file-name> Specify which file the output is written in. DEFAULT is printing on the console. -help Print short help -man 172

183 Chapter 26. The Trifork command line tools Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork domain export mydomainname trifork domain export mydomainname -file MyFile trifork domain import NAME domain import SYNOPSIS trifork domain import [options] <domain-name> <file> DESCRIPTION This command extracts the configuration files for the servers in a domain from a chosen file. If a server is already running, it has no effect on it ARGUMENTS domain-name Specify the domain name. file Specify the file to extract the configuration from OPTIONS -help -man Print short help Print long help. -vmargs <key=value> 173

184 Chapter 26. The Trifork command line tools For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork domain export mydomainname MyFile trifork domain remove NAME domain remove SYNOPSIS trifork domain remove [options] <domain-dir> <domain-name> DESCRIPTION This command removes a domain with the chosen name from the chosen directory. When a domain is removed all the servers in it are stopped ARGUMENTS domain-dir Specify the directory that contains the domain. domain-name Specify the domain name OPTIONS -help -man Print short help Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE 174

185 Chapter 26. The Trifork command line tools trifork domain remove mydomaindir mydomainname http trifork http createendpoint NAME http createendpoint SYNOPSIS trifork http createendpoint [options] <name> DESCRIPTION This command is used for creating a HTTP endpoint. Referrer to the trifork management client command for a graphical interface to configuration of HTTP and other resources. This command requires a running server! ARGUMENTS name Specify a name for the HTTP endpoint OPTIONS -defaulthost <default-host-name> -define -D <key=value> A description of the HTTP endpoint. Will be shown in the management client. -disablehttp Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -description <description-text> If your clients does only support HTTP 1.0 you may need to specify a default host name to be put into the headers, in order to make redirection work properly. Disable http support. -disablehttps Disable https (SSL) support. 175

186 Chapter 26. The Trifork command line tools -enableajp -help Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -httpbacklog <http-backlog< Specify how many request may stay in the http backlog at a given time. DEFAULT is 500 -httpport <http-port> Specify the port the web container communicates on for HTTP traffic. DEFAULT is httpsbacklog <https-backlog> Specify how many request may stay in the https backlog at a given time. DEFAULT is 500 -httpsport <https-port> Specify the port the web container communicates on for HTTPS traffic. DEFAULT is man Enable support for the AJP protocol. Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. 176

187 Chapter 26. The Trifork command line tools -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -virtualhost <virtual-host-name> Specifies which virtual host the HTTP Endpoint binds to. Your clients need to support HTTP 1.1 for this feature to work. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork http createendpoint -disablehttps -httpport 80 myhttpendpoint trifork http removeendpoint NAME http removeendpoint SYNOPSIS trifork http removeendpoint [options] <name> DESCRIPTION This command is used for removing a HTTP endpoint. Referrer to the trifork management client command for a graphical interface to configuration of HTTP and other resources. This command requires a running server! ARGUMENTS name Specify a name of the HTTP endpoint to remove. 177

188 Chapter 26. The Trifork command line tools OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork http removenedpoint myhttpendpoint 178

189 Chapter 26. The Trifork command line tools jdbc trifork jdbc createdatasource NAME jdbc createdatasource SYNOPSIS trifork jdbc createdatasource <connectionurl> [options] <name> <jndiname> <driverclass> <CMPtypemapping> DESCRIPTION This command is used for creating a JDBC datasource. A JDBC datasource should always be used in connection with at pooled datasource. Use trifork jdbc createpooleddatasource to create a pooled datasource Referrer to the trifork management client command for a graphical interface to configuration of JDBC datasource and other resources. This command requires a running server! ARGUMENTS name jndi-name Specify which JDBC driver class to use. Make sure that the JDBC driver class is on the servers classpath by copying the driver jar file to the domains lib/share directory. CMPtypemapping Specify a jndi name for the data source to be bound in naming. driverclass The name of the JDBC datasource to create. Specify a predefined CMP type mappings to be used for the data source. connectionurl Specify a connection URL. The format of the URL depends on your specific JDBC driver. Consult the driver documentation to find the specific format of the URL OPTIONS -dbpassword <database-password> 179

190 Chapter 26. The Trifork command line tools -dbusername <database-username> Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man A description of the JDBC datasource. Will be shown in the management client. -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -description <description-text> Specify the username used when logging into the database. -define -D <key=value> Specify the password used when logging into the database. Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -property <key=value> If you are using an XA driver, you can specify a number of properties with this option. Which properties you need to specify depends on your specific JDBC driver. DEFAULT is no password, in which case the system will prompt for it. 180

191 Chapter 26. The Trifork command line tools -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork jdbc createdatasource mydatasource jdbc/mydatasource com.somecompany.jdbc.driver MyCompany jdbc:somehost:someport/dbname trifork jdbc createpooleddatasource NAME jdbc createpooleddatasource SYNOPSIS trifork jdbc createpooleddatasource [options] <name> <jndiname> <datasource-jndiname> DESCRIPTION This command is used for creating a pooled JDBC datasource. A pooled JDBC datasource should always be used in connection with at JDBC datasource. Use trifork jdbc createdatasource to create a JDBC datasource. Referrer to the trifork management client command for a graphical interface to configuration of JDBC datasource and other resources. This command requires a running server! ARGUMENTS name jndi-name The name of the pooled JDBC datasource to create. The jndi name for the JDBC Pool. This is used for looking up the JDBC pool from your application. datasource-jndiname Specify one of your predefined data sources to create the pool for. 181

192 Chapter 26. The Trifork command line tools OPTIONS -define -D <key=value> -description <description-text> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Print long help. --maxpoolsize <max-pool-size> Print short help -host <host> A description of the JDBC datasource. Will be shown in the management client. -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Specify the maximum number of connections to be made to the database. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. 182

193 Chapter 26. The Trifork command line tools -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork jdbc createpooleddatasource mypooleddatasource jdbc/mypooleddatasource jdbc/mydatasource trifork jdbc removedatasource NAME jms jdbc removedatasource SYNOPSIS trifork jdbc removedatasource [options] DESCRIPTION This command is used for removing a JDBC datasource. Referrer to the trifork management client command for a graphical interface to configuration of JDBC datasources and other resources. This command requires a running server! ARGUMENTS name The name of the JDBC datasource to remove OPTIONS -define -D <key=value> -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man 183

194 Chapter 26. The Trifork command line tools Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork jdbc removedatasource mydatasource trifork jdbc removepooleddatasource NAME jms jdbc removepooleddatasource SYNOPSIS trifork jdbc removepooleddatasource [options] DESCRIPTION This command is used for removing a pooled JDBC datasource. Referrer to the trifork management client command for a graphical interface to configuration of JDBC datasources and other resources. This command requires a running server! ARGUMENTS name 184

195 Chapter 26. The Trifork command line tools The name of the pooled JDBC datasource to remove OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size. 185

196 Chapter 26. The Trifork command line tools EXAMPLE trifork jdbc removepooleddatasource mypooleddatasource jms trifork jms createqueuefactory NAME jms createqueuefactory SYNOPSIS trifork jms createqueuefactory [options] <jndi-name> DESCRIPTION This command is used for creating a JMS Queue Factory. Referrer to the trifork management client command for a graphical interface to configuration of JMS and other resources. This command requires a running server! ARGUMENTS jndi-name Specify a jndi-name for which the JMS Queue Factory will be bound in the server OPTIONS -clientid <clientid> -define -D <key=value> A description of the JMS Queue Factory configuration. Will be shown in the management client. -factorypassword <factory-password> Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -description <description-text> You can optionally specify a client id to be used by the connection factory. Specify the password the connection factory should use when communicating with the JMS-provider. -factoryusername <factory-username> 186

197 Chapter 26. The Trifork command line tools -help Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Specify the user name the connection factory should use when communicating with the JMS-provider. Print long help. -name The name of the JMS Queue Factory. DEFAULT is the jndi-name. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size. 187

198 Chapter 26. The Trifork command line tools EXAMPLE trifork jms createqueuefactory -name myjmsfactory -factorypassword jmsproviderpassword -factoryusername jmsproviderusername jms/myfactory trifork jms createqueue NAME jms createqueue SYNOPSIS trifork jms createqueue [options] <jndi-name> DESCRIPTION This command is used for creating a JMS Queue. Referrer to the trifork management client command for a graphical interface to configuration of JMS and other resources. This command requires a running server! ARGUMENTS jndi-name Specify a jndi-name for which the JMS Queue will be bound in the server OPTIONS -define -D <key=value> -description <description-text> A description of the JMS Queue configuration. Will be shown in the management client. -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Print long help. 188

199 Chapter 26. The Trifork command line tools -name The name of the JMS Queue. DEFAULT is the jndi-name. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork jms createqueue -name myjmsqueue jms/myqueue trifork jms createtopicfactory NAME jms createtopicfactory SYNOPSIS trifork jms createtopicfactory [options] <jndi-name> DESCRIPTION This command is used for creating a JMS Topic Factory. Referrer to the trifork management client command for a graphical interface to configuration of JMS and other resources. This command requires a running server! ARGUMENTS 189

200 Chapter 26. The Trifork command line tools jndi-name Specify a jndi-name for which the JMS Topic Factory will be bound in the server OPTIONS -clientid <clientid> -define -D <key=value> Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Specify the user name the connection factory should use when communicating with the JMS-provider. -help Specify the password the connection factory should use when communicating with the JMS-provider. -factoryusername <factory-username> A description of the JMS Topic Factory configuration. Will be shown in the management client. -factorypassword <factory-password> Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -description <description-text> You can optionally specify a client id to be used by the connection factory. Print long help. -name The name of the JMS Topic Factory. DEFAULT is the jndi-name. 190

201 Chapter 26. The Trifork command line tools -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork jms createtopicfactory -name myjmsfactory -factorypassword jmsproviderpassword -factoryusername jmsproviderusername jms/myfactory trifork jms createtopic NAME jms createtopic SYNOPSIS trifork jms createtopic [options] <jndi-name> DESCRIPTION This command is used for creating a JMS Topic. Referrer to the trifork management client command for a graphical interface to configuration of JMS and other resources. This command requires a running server! ARGUMENTS jndi-name Specify a jndi-name for which the JMS Topic will be bound in the server. 191

202 Chapter 26. The Trifork command line tools OPTIONS -define -D <key=value> -description <description-text> Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man A description of the JMS Topic configuration. Will be shown in the management client. -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -name The name of the JMS Topic. DEFAULT is the jndi-name. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for 192

203 Chapter 26. The Trifork command line tools it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork jms createtopic -name myjmstopic jms/mytopic trifork jms removedestination NAME jms removedestination SYNOPSIS trifork jms removedestination [options] <name> DESCRIPTION This command is used for removing a JMS destination. A JMS destination can either be a JMS Topic and Queue. Referrer to the trifork management client command for a graphical interface to configuration of JMS and other resources. This command requires a running server! ARGUMENTS name The name of the JMS destination which should be removed OPTIONS -define -D <key=value> -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print short help -host <host> If the server runs on remote host, specify the domain manager. 193

204 Chapter 26. The Trifork command line tools -man DEFAULT is local host. Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork jms removedestination myjmstopic trifork jms removefactory NAME jms removefactory SYNOPSIS trifork jms removefactory [options] <name> DESCRIPTION This command is used for removing a JMS factory. A JMS factory can either be a JMS Topic and Queue factory. Referrer to the trifork management client command for a graphical interface to configuration of JMS and other resources. This command requires a running server! 194

205 Chapter 26. The Trifork command line tools ARGUMENTS name The name of the JMS factory which should be removed OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> 195

206 Chapter 26. The Trifork command line tools For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork jms removefactory myjmsfactory mail trifork mail createconfiguration NAME mail createconfiguration SYNOPSIS trifork mail createconfiguration [options] <name> <jndi-name> <mail-from> <mail-user> <mail-host> DESCRIPTION This command is used for creating a mail configuration. Referrer to the trifork management client command for a graphical interface to configuration of mail and other resources. This command requires a running server! ARGUMENTS name jndi-name Specify a sender address which will be used in the headers of mails send with the mail resource. mail-user Specify a jndi-name for which the mail resource will be bound in the server. mail-from Specify a name for the mail configuration to create. Specify the username on the mail server to use when sending mails. mail-host Specify the mailhost to use when sending mail OPTIONS 196

207 Chapter 26. The Trifork command line tools -description <description-text> -define -D <key=value> Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -help A description of the mail configuration. Will be shown in the management client. Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size. 197

208 Chapter 26. The Trifork command line tools EXAMPLE trifork mail createconfiguration MyMailConfiguration mailserver.trifork.com mail/mymailresource "Trifork mail user" trifork mail removeconfiguration NAME mail removeconfiguration SYNOPSIS trifork mail removeconfiguration [options] <name> DESCRIPTION A simple command which is used to remove a mail configuration. Referrer to the trifork management client command for a graphical interface to configuration of mail and other resources. This command requires a running server! ARGUMENTS name Specify the name of the mail configuration to remove OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. 198

209 Chapter 26. The Trifork command line tools DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork mail removeconfiguration mailconfigurationname management trifork management client NAME management client SYNOPSIS trifork management client [options] DESCRIPTION An important aspect of running an application server in production settings is management. The Management Module provides the core management infrastructure, allowing other modules in the server to register JMX(tm) based management agents. The Management module also allows management (client) applications to connect to the server and obtain management information. The trifork management client command starts the management tool, if a server is running. When the application is loaded it presents a login screen. You need to login with administrator privileges. The GUI consists of three main areas: Model Browser: The model browser allows you to browse the management model. The model browser is a tree component showing the JSR-77 J2EE management model. The root element is the J2EEDomain, defining the unit of management. A J2EEDomain consists of deployed objects and servers. The deployed objects node contain nodes describing the archives deployed into the J2EEDomain. The Server node contain a J2EEServer objects for each server instance in the management domain. A J2EEServer node contains chil199

210 Chapter 26. The Trifork command line tools dren describing the Java VM, the operating system, and server resource such as the JTA transaction manager. Toolbar: New Desktop creates a new desktop. You can switch between desktops by clicking on the tabbedpane folders in the desktop area. Inspector Manager activates the InspectorManager tool in the active desktop. The InspectorManager tool shows detailed information about the management object selected in the model browser. Table tool creates a new Table Tool in the active desktop. The Table tool shows statistics from management objects. Use the Table tool to view the statistic attributes of a set of management objects of the same type, e.g. Servlets or EJBs. You add management objects by dragging them from the model browser and dropping them on the table tool. XY chart creates a new XY Chart in the active desktop. The XY Chart tool shows statistics from management objects as a graph. Use the XY Chart tool to view the values of statistic attributes over time. You add statistic attributes by dragging them from the model browser and dropping them on the XY Chart. Desktop Area: is where the different tools lives. The management application supports multible desktops OPTIONS -define -D <key=value> -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Print long help. -updateinterval <seconds> Print short help -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. DEFAULT is 2 seconds -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size. 200

211 Chapter 26. The Trifork command line tools EXAMPLE trifork management client -updateinterval 3 This will start the management client, connecting to the server running on local host, with a three seconds update interval realm trifork realm addgroup NAME realm addgroup SYNOPSIS trifork realm addgroup [options] <group> DESCRIPTION If your application uses J2EE security, your would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. Most of them is used by the example applications bundled with the server. The trifork realm addgroup command adds a group to the internal database of users. This command requires a running server! ARGUMENTS group Specify the name of the group to add to the realm OPTIONS -define -D <key=value> -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print short help -host <host> If the server runs on remote host, specify host. DEFAULT is local host. 201

212 Chapter 26. The Trifork command line tools -man Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -realm <realm> Specify which realm to add group to. DEFAULT is the realm "default". -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm addgroup -realm myrealm newgroup This command adds the group newgroup to the realm named myrealm trifork realm addmember NAME realm addmember SYNOPSIS trifork realm addmember [options] <group> <realm-user> 202

213 Chapter 26. The Trifork command line tools DESCRIPTION If your application uses J2EE security, you would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. Most of them is used by the example applications bundled with the server. The trifork realm addmember command adds a user to a group. This command requires a running server! ARGUMENTS group Specify the name of the group to add the member to. realm-user Specify the name of the user to add to the group OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify host. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -realm <realm> 203

214 Chapter 26. The Trifork command line tools Specify which realm to add member in. DEFAULT is the realm "default". -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm addmember groupname myuser This command adds the user myuser to the group named groupname trifork realm adduser NAME realm adduser SYNOPSIS trifork realm adduser [options] <realm-user> <realm-password> DESCRIPTION If your application uses J2EE security, you would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. Most of them is used by the example applications bundled with the server. The trifork realm adduser command adds a user to the interanel database of users. This command requires a running server! ARGUMENTS realm-user Adds a user with this username to the realm. 204

215 Chapter 26. The Trifork command line tools realm-password Adds a user with this password to the realm OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify host. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -realm <realm> Specify which realm to add user to. DEFAULT is the realm "default". -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for 205

216 Chapter 26. The Trifork command line tools it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm adduser -realm myrealm newuser newpassword This command adds the user newuser with password newpasswordto the realm named myrealm trifork realm create NAME realm create SYNOPSIS trifork realm create [options] <realm-name> <realm-class> DESCRIPTION This command is used for creating a security realm. Referrer to the trifork management client command for a graphical interface to configuration of security and other resources. This command requires a running server! ARGUMENTS realm-name Specify the name for the security realm. realm-class Specify the class name for the security realm OPTIONS -define -D <key=value> Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -help 206

217 Chapter 26. The Trifork command line tools -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -properties <property-list> Print short help Specify a list of key,values properties for the security realm. Each property must be enclosed in []. Which properties to specify depends on the realm class. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork [providerurl=ldap ://localhost:389/dc [u se realm create 207 -properties

218 Chapter 26. The Trifork command line tools rbasedn=ou=people,dc=trifork,dc=com][usernameattribute=cn] com.trifork.eas.security.auth.service.ldaprealm myrealm trifork realm listgroup NAME realm listgroup SYNOPSIS trifork realm listgroup [options] <group> DESCRIPTION If your application uses J2EE security, you would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. Most of them is used by the example applications bundled with the server. The trifork realm listgroup command prints the users in a specific group. This command requires a running server! ARGUMENTS group Specify the group to list the users of OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify host. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> 208

219 Chapter 26. The Trifork command line tools Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -realm <realm> Specify which realm to list group from. DEFAULT is the realm "default". -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm listgroup -realm myrealm mygroup This command lists the users for the group mygroup found in the database myrealm trifork realm list NAME realm list SYNOPSIS trifork realm list [options] DESCRIPTION If your application uses J2EE security, you would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. Most of them is used by the example applications bundled with the server. The trifork realm list command prints the list of users and groups. 209

220 Chapter 26. The Trifork command line tools This command requires a running server! OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify host. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -realm <realm> Specify which realm to list. DEFAULT is the realm "default". -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. 210

221 Chapter 26. The Trifork command line tools -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm list This command lists the users and groups in the internal database trifork realm listuser NAME realm listuser SYNOPSIS trifork realm listuser [options] <realm-user> DESCRIPTION If your application uses J2EE security, you would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. Most of them is used by the example applications bundled with the server. The trifork realm listuser command prints a users data. This command requires a running server! ARGUMENTS realm-user Specify the name of the user OPTIONS -define -D <key=value> -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print short help -host <host> If the server runs on remote host, specify host. 211

222 Chapter 26. The Trifork command line tools -man DEFAULT is local host. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -realm <realm> Specify which realm to list from. DEFAULT is the realm "default". -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm listuser -realm myrealm myuser This command prints the data for the user myuser found in the database myrealm trifork realm remove NAME realm remove SYNOPSIS 212

223 Chapter 26. The Trifork command line tools trifork jms create [options] <realm-name> DESCRIPTION This command is used for removing a security realm. Referrer to the trifork management client command for a graphical interface to configuration of security and other resources. This command requires a running server! ARGUMENTS realm-name Specify the name for the security realm to remove OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify the domain manager. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -server <server-name> Specify server to deploy to. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. 213

224 Chapter 26. The Trifork command line tools -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm remove myrealm trifork realm removegroup NAME realm removegroup SYNOPSIS trifork realm removegroup [options] <group> DESCRIPTION If your application uses J2EE security, you would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. Most of them is used by the example applications bundled with the server. The trifork realm removegroup command removes a group from the internal database of users. This command requires a running server! ARGUMENTS group Specify the group to remove OPTIONS -define -D <key=value> Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -help 214

225 Chapter 26. The Trifork command line tools -host <host> If the server runs on remote host, specify host. DEFAULT is local host. -man Print short help Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -realm <realm> Specify which realm to remove group from. DEFAULT is the realm "default". -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm removegroup mygroup This command removes the group mygroup. 215

226 Chapter 26. The Trifork command line tools trifork realm removemember NAME realm removemember SYNOPSIS trifork realm removemember [options] <group> <user> DESCRIPTION If your application uses J2EE security, you would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. Most of them is used by the example applications bundled with the server. The trifork realm removemember command removes a user from a group. This command requires a running server! ARGUMENTS group Specify the name of the group to remove the member from. realm-user Specify the name of the user to remove from the group OPTIONS -define -D <key=value> -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print short help -host <host> If the server runs on remote host, specify host. DEFAULT is local host. -man Print long help. 216

227 Chapter 26. The Trifork command line tools -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -realm <realm> Specify which realm to remove member from. DEFAULT is the realm "default". -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm removemember mygroup myuser This command removes the user myuser from the group mygroup trifork realm removeuser NAME realm removeuser SYNOPSIS trifork realm removeuser [options] <realm-user> DESCRIPTION If your application uses J2EE security, you would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. Most of them is used by the example applications bundled with the server. 217

228 Chapter 26. The Trifork command line tools The trifork realm removeuser command removes a user from the internal database. This command requires a running server! ARGUMENTS realm-user Specify the name of the user to remove from the realm OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify host. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -realm <realm> Specify which realm to remove user from. DEFAULT is the realm "default". -server <server-name> Specify the server. 218

229 Chapter 26. The Trifork command line tools DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm removeuser myuser This command removes the user myuser trifork realm updateuser NAME realm updateuser SYNOPSIS trifork realm updateuser [options] <realm-user> <realm-password> DESCRIPTION If your application uses J2EE security, you would want to create a number of users and groups in the Trifork Server. By default, the Trifork Enterprise Application Server uses an internal user database to handle J2EE security. When you start the Trifork Enterprise Application Server for the first time, a number of users have been created for you. Most of them is used by the example applications bundled with the server. The trifork realm updateuser command changes the password of a user. The server needs to be running when you execute this command, and the server will ask for a username and password to perform the action. Initially use username/oldpassword, subsequently use username/newpassword. This command requires a running server! ARGUMENTS realm-user Adds a user with this username to the realm. realm-password Adds a user with this password to the realm. 219

230 Chapter 26. The Trifork command line tools OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on remote host, specify host. DEFAULT is local host. -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -realm <realm> Specify which realm to update user in. DEFAULT is the realm "default". -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. 220

231 Chapter 26. The Trifork command line tools -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork realm updateuser myname myoldpassword This command changes the password of the user myname server trifork server create NAME server create SYNOPSIS trifork server create [options] <domain-dir> <server-name> DESCRIPTION The Trifork Enterprise Application Server comes with a default server instance called default. This instance is located in: <TRIFORK_INSTALL_DIR>/domains/default. The trifork server create command creates the files needed for the execution of the server. This command is relevant if you are working in a multiple server domain and want to add a server to the domain. Having created the new server, the last thing you need to do is update your TRIFORK_SERVER_DIR environment variable to point at the new server instance ARGUMENTS domain-dir Specify the directory in which to find the domains. server-name Specify the name of the server to add OPTIONS -define -D <key=value> Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -help 221

232 Chapter 26. The Trifork command line tools -log <category:level> Set log level for log category. The category name should be based on the class name of the component doing the logging. It contains the necessary methods for logging various levels of messages. The set of possible log levels are: debug, info, warn, error and fatal. This option can be used multiple times. DEFAULT is the log levels described in the [TRIFORK_DOMAIN_DIR]servers/[server]/config/log4j-server.xml configuration file at / -man Print short help Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork server create mydomain myserver This command creates the files needed for the server with the name myserver trifork server export NAME server export SYNOPSIS trifork server export [options] <server-name> DESCRIPTION This command exports the configuration of server to an XML file. This is relevant for back-up of the configuration ARGUMENTS server-name Specify the server, which configuration is to be saved OPTIONS -define -D <key=value> 222

233 Chapter 26. The Trifork command line tools -file <file-name>. Specify the file to which the server configuration should be written. DEFAULT is printing on the console. -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print short help -log <category:level> Set log level for log category. The category name should be based on the class name of the component doing the logging. It contains the necessary methods for logging various levels of messages. The set of possible log levels are: debug, info, warn, error and fatal. This option can be used multiple times. DEFAULT is the log levels described in the [TRIFORK_DOMAIN_DIR]servers/[server]/config/log4j-server.xml configuration file at / -man Print long help EXAMPLE trifork server export myserver -file myfile trifork server import NAME server import SYNOPSIS trifork server import [options] <server-name> <file> DESCRIPTION To make a backup of the server configuration, the command trifork server export can be called. trifork server export saves the configuration of the server in an XML file. The trifork server import command imports this XML file. Do not import a configuration file to a running server, since this can have unforseen sideeffects ARGUMENTS server-name Specify the server, for which the configuration should be fetched. 223

234 Chapter 26. The Trifork command line tools file Specify the file that contains the configuration OPTIONS -define -D <key=value> -help Print short help -log <category:level> Set log level for log category. The category name should be based on the class name of the component doing the logging. It contains the necessary methods for logging various levels of messages. The set of possible log levels are: debug, info, warn, error and fatal. This option can be used multiple times. DEFAULT is the log levels described in the [TRIFORK_DOMAIN_DIR]servers/[server]/config/log4j-server.xml configuration -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork server import myserver myfile This command imports the configuration found in myfile for myserver trifork server remove NAME server remove SYNOPSIS trifork server remove [options] <domain-dir> <server-name> DESCRIPTION 224 file at /

235 Chapter 26. The Trifork command line tools In a multiple server domain, servers can be added. With the trifork server create command, files needed for the execution of the server are created. This command removes the files that was created ARGUMENTS domain-dir Specify the directory in which to find the domains. server-name Specify the server which is to be removed. This means that the files created for it are deleted OPTIONS -define -D <key=value> -help Print short help -log <category:level> Set log level for log category. The category name should be based on the class name of the component doing the logging. It contains the necessary methods for logging various levels of messages. The set of possible log levels are: debug, info, warn, error and fatal. This option can be used multiple times. DEFAULT is the log levels described in the [TRIFORK_DOMAIN_DIR]servers/[server]/config/log4j-server.xml configuration -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork server remove mydomain myserver This command removes the files created for the server named myserver. 225 file at /

236 Chapter 26. The Trifork command line tools trifork server start NAME server start SYNOPSIS trifork server start [options] DESCRIPTION This command starts the Trifork Enterprise Application Server. To start a server, some prerequisits are necessary. First a domain has to be created, this is done with the trifork domain create command. Second some environment variables need to be set; TRIFORK_INSTALL_DIR must be set to the installation directory, TRIFORK_DOMAIN_DIR must be set to the domain-directory, and the environment can be set with the settriforkdomainenv script in the $TRIFORK_DOMAIN_DIR directory. This script is created when a domain is created, and contains the configuration for running the server in this domain. The server can be started in different modes. In the devel mode all the exceptions occurring in the running server are shown. In the profile mode, the profiling data is accumulated and this data can be queried in a browser at: [localhost:port]/profile. In the debug mode, the JVM is started in debug mode. When the JVM is in debug mode, the JPDA provides a way both to inspect the state and to control the execution of applications running in the JavaTM Virtual Machine, e.g. the server OPTIONS -debug The server is running in the JVM, with the JVM in debug mode. DEFAULT is that the JVM is not in debug mode. -define -D <key=value> -devel The server is running in development mode and thus, all exceptions are shown. DEFAULT is that only the exceptions needed for using the server are printed. -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print short help -log <category:level> Set log level for log category. The category name should be based on the class name of the component doing the logging. It contains the necessary methods for logging various levels of messages. The set of possible log levels are: debug, info, warn, error and fatal. This option can be used multiple times. DEFAULT is the log levels described 226 in the configuration file at /

237 Chapter 26. The Trifork command line tools servers/[server]/config/log4j-server.xml -man Print long help. -node <node-name> This option is relevant for servers in a cluster. The node specified overwrites the one set by the trifork script. DEFAULT is the local machine. -profile Enable the semantic profiler. Accumulate profiling information. DEFAULT is no profiling. -server <server-name> Specify server to start. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork server start -log com.trifork.eas:debug -profile This command starts the server in profile mode, where you are able to be able to browse the call graph of the applications running in the application server. Furthermore the log is created on debug level, where the details of the running server can be seen. trifork server start -node mymachine -define key1=value1 -define key2=value2 This command starts the server in standard mode with no debugging, profiling or extra exceptions. Furthermore the property key1 is set to value1 and the property key2 is set to value2. In the $TRIFORK_DOMAIN_DIR/bin the script starttriforkserver-servername starts the server trifork server stop NAME server stop SYNOPSIS 227

238 Chapter 26. The Trifork command line tools trifork server stop [options] DESCRIPTION This command stops the Trifork Enterprise Application Server. Unless the -host option is used to specify where to find the domain manager, this will stop the server instance running on the local host. This command requires a running server! OPTIONS -define -D <key=value> -help Print short help -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -log <category:level> Set log level for log category. The category name should be based on the class name of the component doing the logging. It contains the necessary methods for logging various levels of messages. The set of possible log levels are: debug, info, warn, error and fatal. This option can be used multiple times. DEFAULT is the log levels described in the [TRIFORK_DOMAIN_DIR]servers/[server]/config/log4j-server.xml configuration file at / -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -server <server-name> Specify server to stop. This is relevant in a multiple server domain. DEFAULT is the server found in the environment variable. 228

239 Chapter 26. The Trifork command line tools -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork server stop -server myserver This command stops the specified server system trifork system create NAME system create SYNOPSIS trifork system create [options] <system-name> DESCRIPTION Before an application can be deployed to the Trifork Enterprise Application Server, a system container has to be created. To actually deploy the archive, the command trifork archive deploy is used. Deployed J2EE enterprise application archives (EAR) are at runtime hosted by instances of the System Container Module. Each System Container contains an EJB Container and a Web Container. The EJB and Web containers hosts the Web and EJB modules contained in the EAR, respectively. System Container Modules can be independently configured and rebooted on the fly. For a server system hosting multiple J2EE applications (or JSP/Servlet based web sites); this means that while one system requires maintenance or updating, other systems can continue undisturbed. The trifork system create command creates a system container. A system container is automatically started after it has been created. The system must be created on a running server, either the default server found in the environment variable or a specified server. This command requires a running server! ARGUMENTS system-name Specify the name of the system to be created. 229

240 Chapter 26. The Trifork command line tools OPTIONS -define -D <key=value> -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Print short help -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork system create -host mydomain_mgr_host -server myserver mysystem 230

241 Chapter 26. The Trifork command line tools The command creates a system container with the name mysystem on the host mydomain_mgr_host. In a multiple server environment, the server has to be specified, in this case myserver trifork system list NAME system list SYNOPSIS trifork system list [options] DESCRIPTION Deployed J2EE enterprise application archives (EAR) are at runtime hosted by instances of the System Container Module. Each System Container contains an EJB Container and a Web Container. The EJB and Web containers hosts the Web and EJB modules contained in the EAR, respectively. This command lists system containers on a server. This command requires a running server! OPTIONS -define -D <key=value> -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Print short help -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -server < server-name> 231

242 Chapter 26. The Trifork command line tools Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE In a multiple server domain, it is necessary to identify the server: trifork system list -host domain_mgr_host -server myserver This command lists the system containers created for the server myserver. In a single server domain, the server will be found via the environment variables: trifork system list trifork system list -host hostname trifork system remove NAME system remove SYNOPSIS trifork system remove [options] <system-name> DESCRIPTION Deployed J2EE enterprise application archives (EAR) are at runtime hosted by instances of the System Container Module. Each System Container contains an EJB Container and a Web Container. The EJB and Web containers hosts the Web and EJB modules contained in the EAR, respectively. This command removes a system container, that has been created by the command trifork system create. The system container cannot be removed, before it is stopped. This command requires a running server! ARGUMENTS system-name 232

243 Chapter 26. The Trifork command line tools Specify the name of the system to be removed OPTIONS -define -D <key=value> -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Print short help -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size. 233

244 Chapter 26. The Trifork command line tools EXAMPLE trifork system remove mysystem This command removes the system mysystem related to the server found in the environment variable on the local host trifork system restart NAME system restart SYNOPSIS trifork system restart [options] < system-name > DESCRIPTION Deployed J2EE enterprise application archives (EAR) are at runtime hosted by instances of the System Container Module. Each System Container contains an EJB Container and a Web Container. The EJB and Web containers hosts the Web and EJB modules contained in the EAR, respectively. This command stops and then starts a system container. This command requires a running server! ARGUMENTS system-name Specify the name of the system to be restarted OPTIONS -define -D <key=value> -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print short help -man 234

245 Chapter 26. The Trifork command line tools Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork system restart mysystem This command stops and then restarts the system tmysystem on the default server trifork system start NAME system start SYNOPSIS trifork system start [options] <system-name> DESCRIPTION Deployed J2EE enterprise application archives (EAR) are at runtime hosted by instances of the System Container Module. Each System Container contains an EJB Container and a Web Container. The EJB and Web containers hosts the Web and EJB modules contained in the EAR, respectively. This command starts a system container. A system container is automatically started after it has been created by the command trifork system create. When a system container is already started, it cannot be started again. This command requires a running server! 235

246 Chapter 26. The Trifork command line tools ARGUMENTS system-name Specify the name of the system to be started OPTIONS -define -D <key=value> -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Print short help -man Specify java properties to be delegated to the virtual machine. This option can be used multiple times. Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> 236

247 Chapter 26. The Trifork command line tools For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork system start -username myname mysystem This command starts a system by the name mysystem by the user myname trifork system stop NAME system stop SYNOPSIS trifork system stop [options] <system-name> DESCRIPTION Deployed J2EE enterprise application archives (EAR) are at runtime hosted by instances of the System Container Module. Each System Container contains an EJB Container and a Web Container. The EJB and Web containers hosts the Web and EJB modules contained in the EAR, respectively. This command stops a system container. This command requires a running server! ARGUMENTS system-name Specify the name of the system to be stopped OPTIONS -define -D <key=value> Specify java properties to be delegated to the virtual machine. This option can be used multiple times. -host <host> If the server runs on a remote host, specify the host. DEFAULT is localhost. -help Print short help 237

248 Chapter 26. The Trifork command line tools -man Print long help. -password <password> Specify the password of the user executing the command. This option is to be used together with the user option. DEFAULT is no password, in which case the system will prompt for it. -server <server-name> Specify the server. DEFAULT is the server found in the environment variable. -username <username> Specify the user executing the command. If no user is found in the login file, the system will prompt for it. DEFAULT is the user found in the login file. -vmargs <key=value> For other parameters that you may want to control, such as heap and stack size EXAMPLE trifork system stop mysystem This command stops the system, mysystem, on the default server. 238

249 Chapter 27. The Trifork ant tools This chapter contains detailed information about the Trifork ant integration. It is now possible in a standardized way to automate most of the tasks involved in building and deploying applications on the Trifork Enterprise Application Server. For more information on ant see Apache Ant [ Getting started Using the Trifork Ant Tasks only requires af few simple steps: 1. Set environment variable ANT_HOME to <INSTALLATION_DIR>/server/ant 2. Add <INSTALLATION_DIR>/server/ant/bin to your PATH. 3. Set the property trifork.domain.dir in your ant project pointing to the domain you want to use. This property is used by all the trifork ant tasks except domaincreate. 4. Set the property trifork.install.dir in your ant project pointing to the Trifork server. This property is used by the domaincreate task. Example: <?xml version="1.0"?> <project name="taskexample" default="main" basedir="."> <target name="init"> <property name="trifork.domain.dir" value="c:/trifork-3.2/domains/default" /> <property name="trifork.install.dir" value="c:/trifork-3.2/server" /> </target> <target name="main" depends="init"> <trifork> <serverstart devel="true"/> <systemcreate system="mysystem"/> <serverstop/> </trifork> </target> </project> Using your own ant installation It is also possible to use the Trifork Ant Tasks from your own ant installation. This only requires two additional steps: Copy the file "trifork-tools-ant.jar" from <INSTALLATION_DIR>/server/ant/lib to the lib directory of your ant installation. Add the following to your ant name="com.trifork.eas.anttasks.triforktask" /> project <taskdef name="trifork" class- Or Edit the file org/apache/tools/ant/taskdefs/defaults.properties, found in the archive "ant.jar" in the lib directory of your ant installation, adding the line trifork=com.trifork.eas.anttasks.triforktask. 239

250 Chapter 27. The Trifork ant tools archive convert For a description of the archive convert command see Section Parameters Table Attribute Description archive The archive you want to convert as a full-path filename. Required Yes overwrite Force overwrite triforkapp-conf.xml. If a legacy xml-file exists, the deployment of the archive can have unforseen consequences. Default is no overwrite. No Examples <archiveconvert archive="myarchive"/> deploy For a description of the archive deploy command see Section Parameters Table Attribute Description Required system The name of the system-container to deploy into. Yes archive The archive to deploy as a full-path filename. Yes username The username to connect with. No password The password to connect with. No appname Specify application name. Default is the application assembled in the archive. No bundledir Specify a local directory to have the generated client bundless stored into. By default the trifork archive deploy command will store the client bundles in the application servers repository. From there they can be started by using the clientlauncher tool. In special cases you No 240

251 Chapter 27. The Trifork ant tools Attribute Description Required may choose to run the client using the trifork client run command. In these cases you will need direct access to the client bundles. descriptor Supply the trifork-app-conf.xml descriptor. For each component type, the deployment specifications define the files required and their location in the directory structure. The Trifork server requires an additional trifork-app-conf.xml file. This way, it does not have to be included in the archive, and the archive will remain portable. Default is the triforkapp-conf.xml file included in the application package. No host If the server runs on remote host, specify the domain manager. Default is local host. No iiop Generate iiop stubs for CORBA clients. Default is no generation. No inplace The developer want the application to respond to source code changes as fast as possible. The server will create a link from its repository to the application being deployed instead of creating a copy. Thus making the deployment process a lot faster. Using this option a directory instead of an archive should be specified in the command line. This gives a great advantage during development, as applications being developed doesn't have to be packed each time a redeployment is needed. Default is copying. No noactivation The deployed version is not activated. Default is activation. No nojspcompilation Disable precompilation of JSPs. Default is precompilation. By doing this, all compilation errors are catched during deployment. To have your JSPs precompiled, just make sure that they are all named in the web.xml file. No norestart Do not restart system container. Default is restart. No noxmlvalidation Disable DTD validation of XML descriptors. Default is validation. No server Specify server to deploy to. This is relevant in a multiple server domain. Default is the server found in the environment variable. No type Specify which type of archive to deploy (web ejb ear rar client). This overrides the guessing procedure based on extensions. Default is us- No 241

252 Chapter 27. The Trifork ant tools Attribute Description Required ing a guessing procedure based on extensions. version Specify application version. Default is the current version of the application. No Examples <archivedeploy system="mysystem" archive="myarchive"/> <archivedeploy system="mysystem" archive="mydirectory" type="client"/> undeploy For a description of the archive undeploy command see Section Parameters Table Attribute Description Required system The name of the system-container to undeploy from. Yes appname The name of the application to undeploy. Yes appversion The application version. No username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server to undeploy from. This is relevant in a multiple server domain. Default is the server found in the environment variable. No norestart Do not restart system container. Default is restart. No Examples <archiveundeploy system="petstore_container" appname="petstore" appversion="1"/> 242

253 Chapter 27. The Trifork ant tools auth login For a description of the auth login command see Section Parameters Table Attribute Description username The username to connect with. Required Yes password The password to connect with. Yes host If the server runs on remote host, specify the domain manager. Default is local host. No Examples <authlogin username="user" password="pass"/> logout For a description of the auth logout command see Section Parameters Table Examples <authlogout/> domain create For a description of the domain create command see Section Parameters Table

254 Chapter 27. The Trifork ant tools Attribute Description basedir The full path of the directory to create the domain in. Required Yes domain The name of the domain to create. Yes server The name of the server to create in the new domain. Yes Examples <domaincreate basedir="c:\trifork-3.2\domains" domain="mydomain" server="myserver" /> export For a description of the domain export command see Section Parameters Table Attribute Description Required domain The name of the domain to export. Yes file Specify which file the output is written in. Default is printing on the console. No Examples <domainexport domain="mydomain" file="c:\mydomain.xml" /> import For a description of the domain import command see Section Parameters Table Attribute Description Required domain The name of the domain to import to. Yes file Specify which file the input is read from. Yes 244

255 Chapter 27. The Trifork ant tools Examples <domainimport domain="mydomain" file="c:\mydomain.xml" /> remove For a description of the domain remove command see Section Parameters Table Attribute Description Required basedir The full path of the directory to remove the domain from. Yes domain The name of the domain to remove. Yes Examples <domainremove basedir="c:\trifork-3.2\domains" domain="mydomain" /> realm addgroup For a description of the realm addgroup command see Section Parameters Table Attribute Description Required group The name of the group to add. Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples 245

256 Chapter 27. The Trifork ant tools <realmaddgroup group="mygroup"/> addmember For a description of the realm addmember command see Section Parameters Table Attribute Description group The name of the group to add to. Required Yes user The name of the user to add to the group. Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <realmaddmember group="mygroup" user="myuser" /> adduser For a description of the realm adduser command see Section Parameters Table Attribute Description Required realmuser The name of the user to add. Yes realmpassword The password of the user to add. Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No 246

257 Chapter 27. The Trifork ant tools Attribute Description server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. Required No Examples <realmadduser realmuser="myuser" realmpassword="mypassword" /> listgroup For a description of the realm listgroup command see Section Parameters Table Attribute Description Required group The name of the group to list. Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <realmlistgroup group="mygroup" /> list For a description of the realm list command see Section Parameters Table Attribute Description Required username The username to connect with. 247 No

258 Chapter 27. The Trifork ant tools Attribute Description password The password to connect with. Required No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <realmlist /> listuser For a description of the realm listuser command see Section Parameters Table Attribute Description user The name of the user to list. Required Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <realmlistuser user="myuser" /> removegroup For a description of the realm removegroup command see Section Parameters 248

259 Chapter 27. The Trifork ant tools Table Attribute Description Required group The name of the group to remove. Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <realmremovegroup group="mygroup"/> removemember For a description of the realm removemember command see Section Parameters Table Attribute Description Required group The name of the group to remove from. Yes user The name of the user to remove from the group. Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <realmremovemember group="mygroup" user="myuser" /> 249

260 Chapter 27. The Trifork ant tools removeuser For a description of the realm removeuser command see Section Parameters Table Attribute Description Required user The name of the user to remove. Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <realmremoveuser user="myuser" /> updateuser For a description of the realm updateuser command see Section Parameters Table Attribute Description Required realmuser The name of the user to update. Yes realmpassword The new password of the user to update. Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No 250

261 Chapter 27. The Trifork ant tools Examples <realmupdateuser realmuser="myuser" realmpassword="newpassword" /> create For a description of the realm create command see Section Parameters Table Attribute Description Required name The name of the realm to create. Yes class The realm implementation class for the realm. Yes properties A list of key=value property pairs for the realm. Each pair must be enclosed in [] No username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <realmcreate name="myrealm" class="com.trifork.eas.security.auth.service.ldaprealm" properties="[ remove For a description of the realm remove command see Section Parameters Table Attribute Description Required name The name of the realm to remove. Yes username The username to connect with. No password The password to connect with. No 251

262 Chapter 27. The Trifork ant tools Attribute Description host If the server runs on remote host, specify the domain manager. Default is local host. Required No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <realmremove name="myrealm" /> server start For a description of the server start command see Section Parameters Table Attribute Description Required server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No debug Start the server in debug mode (true false). Default is false. No devel Start the server in devel mode (true false). Default is false. No profile Start the server with profiling information enabled (true false). Default is false. No Examples <serverstart devel="true" profile="true" /> stop For a description of the server stop command see Section Parameters 252

263 Chapter 27. The Trifork ant tools Table Attribute Description Required server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <serverstop /> system create For a description of the system create command see Section Parameters Table Attribute Description Required system The name of the system to create. Yes realm The security realm for the system. No enableautorestart Enable the auto restart functionality for the system. No monitoringinterval Set the monitoring interval (in seconds) for the system. No username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <systemcreate system="mysystem" /> 253

264 Chapter 27. The Trifork ant tools list For a description of the system list command see Section Parameters Table Attribute Description Required username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <systemlist /> remove For a description of the system remove command see Section Parameters Table Attribute Description Required system The name of the system to remove. Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <systemremove system="mysystem" /> 254

265 Chapter 27. The Trifork ant tools start For a description of the system start command see Section Parameters Table Attribute Description system The name of the system to start. Required Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No Examples <systemstart system="mysystem" /> stop For a description of the system stop command see Section Parameters Table Attribute Description Required system The name of the system to stop. Yes username The username to connect with. No password The password to connect with. No host If the server runs on remote host, specify the domain manager. Default is local host. No server Specify server. This is relevant in a multiple server domain. Default is the server found in the environment variable. No 255

266 Chapter 27. The Trifork ant tools Examples <systemstop system="mysystem" /> 256

267 Part IX. The Trifork Profiler The Trifork Enterprise Application Server includes a complete built-in component profiler, which is quite easy to use. This guide gives a short introduction to start using the profiler with the Trifork Enterprise Application Server.

268 Chapter 28. Trifork Profiler Example Profiling an application By running a small bundled example this chapter will demonstrate how to use the embeded profiler to optimize an application. The example, called profex.ear can be found in INSTALLATION_DIRECTORY/samples/profex. It is assumed that the reader is somewhat familiar with the terms system container, J2EE applications and deployment in general. Create a system container called profex: trifork system create profex - and deploy the application: trifork archive deploy profex profex.ear The application can be accessed from your browser at the following url: Figure The profex application The application draws a graph simulating the output from a fictive power plant. It has 2 controls/buttons of in258

269 Chapter 28. Trifork Profiler Example terest: Generate report and Swap to fast version. The Generate report button shows the graph. Note that, though the drawing of the graph is meant to consume a considerable amount of time, the very first time the button is pressed, it also produces some data and inserts it into the databse - which takes some extra seconds (if default settings have not been changed, the internal hsql database is being used). To generate the report the application basically selects (joins) a large set of data from two tables. The idea is that the selection should be very slow. Then by using the profiler, we will determine the bottleneck and modify the data layout, which is done with the Swap to fast version. This adds an index to each of the tables and after this operation, the Generate report is much faster. Press Generate report to make sure the databse is set up before we start. After a while, the following web page appears: Figure The profex application after Generate report Starting the profiler To enable profiling the server must be running in profile mode. Shut down the server, if running, and start it again: trifork server start -profile (Note, if you're used to run the server in devel-mode, you may add the -devel option to the command.) The server responds with: J2EE Semantic Profiler enabled Once the server has started up, you access the profiler from your browser at Here, you must login using the server's administrator account: 259

270 Chapter 28. Trifork Profiler Example Figure Profiler login If default settings haven't been changed, your administrator password is trifork. Now, the profiler opens with the following view: Figure The profiler's main window The profiler works by meassuring the time spent by every call inside the server. Since every call to the application origins from inside the server, almost any call (method) inside the application may be profiled by determining the time from invocation until it returns to the server again. By default the profiler shows a few things: First of all, the callgraph - a tree showing what has been profiled so far. On the tree nodes, a few numbers are printed to state various information about each call. This will be described in further details later on. In the upper right corner, you'll find 4 buttons: 260

271 Chapter 28. Trifork Profiler Example Figure The profiler's controls The first one of interest is the one marked by: Figure Start/stop profiler By clicking here, you'll start profiling - which is what we're going to do now. The case is that the Generate report functionality of the application seems too slow - let's find out why. Start the profiler by clicking the button Figure You'll see that the profiler responds by showing that the clock is ticking. Shift to the browser with the application running and press Generate report. (It's assumed that the Generate report has already been pressed once so appropriate data exists in the database). Switch back to the profiler's browser and press the same icon again to stop profiling Figure Now, the profiler responds by stopping the watch and shows a callgraph of what has been running (ie. what has been profiled). Since profiling very much depends on the computer being used, the exact numbers in your profiler's view and those in the following screen shots will differ. But the overall picture looks like this: Figure First profile run 261

272 Chapter 28. Trifork Profiler Example The callgraph shows that two items have been activated: profex.war and J2EE Profiler. At the left edge of each of the two tree nodes, a number has been printed. This number shows how much of the total time was spent in each node. Here, it shows that 99.1% of the time was consumed by profwx.war and the rest - 0.9% took place inside the profiler itself. Note that this indicates that running the profiler actually yields a very little overhead less that 1% of the total time was spent by the profiler itself. To the right of each node three numbers have been printed: The first one, invocation count, states the number of invocations of each node. Then follows local time which tells how much time was spent inside the node itself, which makes more sense compared to the third column: accumulated time. This one states the total time spent inside the node, ie. spent by the node itself and by the calls further inside of it. These numbers are, for now of little interest - though it shows that the call took seconds to complete inside profex.war. To dive further into what consumes the time, we'll have to expand the tree node: Figure First profiler run expanded Here it shows that the 99.1% of the total time spent inside profex.war was consumed by three children: Graph.service consumed 98.2%, report.jsp took 0.4% and the remaining 0.3% was spent inside FileServlet.service. Note, the coloring of the circle to the left of each node, the darker the color, the more time spent by the node itself. This shows us that all of the time used by FileServlet.service was actually spent by the method itself - which is no big surprise since it has no children. But looking at the color of report.jsp tells us that some time was spent by the node itself and some time was consumed further inside of it. Moving to 262

273 Chapter 28. Trifork Profiler Example Graph.service, which is all white shows that practically all the time was spent by its children. The coloring may be verified by comparing the colums local time and accumulated time. Note that the numbers of accumulated time don't sum up to complement each other. This fact reflects the filter settings, which we will discuss later on. For now, the thing of interest is to find out what takes so much time inside of Graph.service ( seconds). Expand this node and keep expanding the node that consumes the most time - this ends up with the following picture: Figure First profiler run further expanded It shows that CallableStatement.executeQuery takes almost all the time - here seconds. The bottleneck of the application has been identified. CallableStatement.executeQuery is the subject to change to get a faster application. And since this method doesn't do anything but execute a query in the database, the database layout or the use of if is very likely to be the real bottleneck. Pressing the >> symbol to the left of the topmost node adds a colored bar to the tree. Using the same color scheme as mentioned above it gives a graphical view of how time was spent inside each node. Figure Color bars added to the callgraph 263

274 Chapter 28. Trifork Profiler Example To change the use of the database, switch to the browser running the application ant press Swap to fast version. Having done that, let's try to profile the application once more. Press the start profile icon: Figure Then click Generate report and stop the profiler again. This gives the following picture: Figure Second profiler run 264

275 Chapter 28. Trifork Profiler Example Please note that now the profiler has consumed 12.3% of the total time. This does not indicate that the profiler has grown slower - it only indicates that the 230 ms spent by the profiler is quite a lot compared to the time used by the faster application. Profiling a "real" application typically yields an overhead in performance of less than 5%. It shows that executing profex.war has taken seconds (which is quite a difference compared to the 20 seconds from the slower version). By expanding the node a few times, we get: Figure Second profiler run expanded Here it shows that 901 ms of the total time has been spent by CallableStatement.executeQuery. Though this is a simple and somwhow theoretic example, it shows the principles of profiling an application. Real" applications, however, often have more than one bottleneck, which even may not be as massive as the one from the example Hot spots Expand the report.jsp node. This gives you the following picture: Figure Second profiler run further expanded 265

276 Chapter 28. Trifork Profiler Example Identify the ProfilerSampleBean.ensureSetup node - you'll find it twice in the callgraph, once invoked from report.jsp and once invoked from Graph.service. Adding the numbers printed on each of these two nodes gives us that 7.0% + 3.2% = 10.2% of the total time was spent inside ProfilerSampleBeen.ensureSetup. Click on the circle to the left of any one of the appearances of the node - now a new tree opens up below the callgraph: Figure The hotspot graph (inverse callgraph) 266

277 Chapter 28. Trifork Profiler Example The tree has been turned upside down: The children of the root node ProfilerSampleBean.ensureSetup are the actual parents: report.jsp and Graph.service. The direction of the callgraph - here the inverse callgraph - has been marked with an arrow on each of the colored circles to the left of each node. The arrows of the inverse callgraph points to the upper left; in the "normal" callgraph above they point to the lower right. This shows the direction of the callgraph. A number has been printed with black next to the circle of ProfilerSampleBean.ensureSetup. It indicates the total amount of time spent inside the tree node (which was calculated above: 7.0% + 3.2% = 10.2%). The numbers printed with red - (here 0%, 1.1% and 21.0%) state the percentage of local time spent inside each method. For instance, from the callgraph we get that 391 ms was consumed locally inside Graph.service. The total accumulated time spent by the invocation from Generate report from the application adds up to: 1634 ms inside profex.war plus 230 ms inside J2EE Profiler = 1864 ms. Hence 391 ms divided by 1864 ms = 21% of the time was spent inside Graph.service. The inverse callgraph may be turned back by clicking the colored circle of ProfilerSampleBean.ensureSetup: Figure The hotspot graph Now the callgraph looks familiar again - except for the fact that numbers reference to ProfilerSampleBean.ensureSetup which is the root of the tree Views Click the graph again to switch back to the inverse callgraph and click the configure views button in the upper right corner of the window: Figure Configure views 267

278 Chapter 28. Trifork Profiler Example Now a new window opens: Figure The profiler's configure views window Here you'll find the settings for the callgraph and the hotspot graph. Through this window it is possible to configure which data/numbers to show. The window allows you to configure a number of settings; at the top of the window you'll find a list of all configured views. By default the list contains one element: default: Figure List of active views 268

279 Chapter 28. Trifork Profiler Example Under the list, the current view appears in the box labeled Setting name: Next to the list of the configured views, the label New shows. Click here. Now, the current view Setting name changes to New. Change the name to Hotspotview: Figure Defining a new view Now that you have given the new customised view a name, lets configure it. The settings have been split into two major sections: Callgraph and Hotspots with almost the same possible settings. Only difference is that Hotspots has an extra paramter called Rootnode. The drop-down boxes state what information to print on the tree nodes: Sortorder lets you select the data that determines the order of the tree nodes at the same level (tree nodes having the same parent). Opennode is the information to be printed at the left edge of each expanded node. Closednode tells what to print at the left edge of each collapsed node. The same way, Rootnode configures what to show on the root of the hotspot graph (if any). Details determines which colums to print at the right of each node. Note that multiple selections are allowed in the Details box. Select the following: Callgraph - Sortorder: Accumulated time - Opennode: Accumulated time percent of total - Closednode: Accumulated time percent of total - Details: Local time, Accumulated time Hotspots - Sortorder: Local time - Rootnode: Local time percent of total - Opennode: Invocations / parent invocation - Closednode: Invocations / parent invocation - Details: Local time, Accumulated time, Invocation count Figure Configuring the new view 269

280 Chapter 28. Trifork Profiler Example Press Save - now the window closes, and the view has been added to the main window: Figure Main window's views 270

281 Chapter 28. Trifork Profiler Example The new view Hotspotview has been highlighted but the callgraph and the hotspot graph haven't been updated with the new information. Expand the callgraph and find ProfilerSampleBean.ensureSetup. Put a hotspot on the node (method) the way you did it earlier and expand report.jsp. Now the screen looks like this: Figure The new hotspot graph Note the number 1 printed with blue on the two nodes report.jsp and Graph.service and the 11 on profex.war. These numbers reflect the setting you've just made (Invocations / parent invocation) which tells that every time profex.war was invoked 11 times, it invoked report.jsp one time. (The 11 invocations has to do with the nature of the application - each click on Generate report produces 11 calls to the actual application.) Open the settings window again: Figure

282 Chapter 28. Trifork Profiler Example and take a look at the possible selections: Figure View's possible selections Please note that all options reflect various arithmetic operations with only a few sets of data. Actually the profiler meassures very few paramteres, the interpretation of the numbers is the essense of the profiler application. For the same reason it is very difficult to make a view that suits every possible case; the default view is, though, a rather good set og basic configurations Filters A lot of redundant information has been filtered away from the callgraph. In most cases, information about network, RMI and so on is of very little interest. The default settings of the profiler hide these things from the user. 272

283 Chapter 28. Trifork Profiler Example However, if you were to see this kind of information, the filter settings may be changed. Click on the Configure filters in the top right of the window: Figure Configure filters This pops up a new window: Figure Filter configuration window 273

284 Chapter 28. Trifork Profiler Example The filter view is basically a number of categories that may be shown or hidden from the callgraph. Change RMI to selected and press Save. The callgraph has now changed, for instance the call to ProtableRemoteObject.narrow: Figure Callgraph with new filter settings Open the filter configuration window again and take a look at all the categories. Most of them origin from the APIs coverd by the J2EE platform but a couple of them has to do with the internal architecture of the Trifork Enterprise Application Server. Deselct RMI again and select J2EE Runtime and Trifork runtime. Expand report.jsp and ejbcreate. Here a couple of extra nodes have appeared showing more details of the complexity that actually lies behind every invocation from the client: Figure Callgraph with new filter settings 274

285 Chapter 28. Trifork Profiler Example Reopen the filter settings window and change the Hide threshold limit to 5 ms. Save and take a look at the callgraph: Figure Callgraph with new filter settings Now the nodes that consumes less than 5 ms have been hidden. This may be very useful since profiling for performance very often is a matter of identifying the bigger consumers. Note that DataSource.getConnection still 275

286 Chapter 28. Trifork Profiler Example shows though its local time has a value of 0 ms. This is due to the fact that its accumulated time (110 ms) exceeds the threshold so its children are still of interest. As mentioned in the section describing views, the exact configuration of which packages to show and which to hide is often a determined by the nature of the application and what is to be profiled. But in many cases, the default settings correspond to the actual needs. 276

287 Part X. Example applications bundled with the Trifork Enterprise Application Server A number of example application are bundled with the Trifork Enterprise Application Server. This guide presents these.

288 Chapter 29. Simple examples This chapter contains a number of simple examples, which can act as a starting point if you are not used to develop for the J2EE platform. Each example show a limited set of J2EE components, and how they interact. Common for all the examples is that it is explained how they are coded, assembled and deployed. The examples are: A CMP bean accessed though a Servlet A BMP bean accessed through a Servlet A Session bean accessed through a JSP All the examples can be found in the INSTALLATION_DIRECTORY/samples directory Entity Bean using CMP This example shows how to write and deploy an enterprise entity bean using container-managed persistence (CMP) in the Trifork Enterprise Application Server. It shows some of the new features in EJB 2.0, e.g. how to use EJB-QL and the changes in how to implement the bean class. It also shows some of the special features available in the Trifork Enterprise Application Server regarding container-managed persistence. The example shows how to construct an entity bean (Sample) that can store a string persistently using containermanaged persistence. The example shows how the Sample entity bean can be accessed from a servlet (SampleServlet). The SampleServlet uses the Sample entity bean to store the timestamp and the client of the last access to the Sample entity, and the SampleServlet then renders this timestamp and shows the client name along with the current time as output. The example is divided into the following parts, which are described successively: Writing the Entity Bean Writing the Servlet Writing the Deployment Descriptors Building, deploying, and running the example Source code, deployment descriptors, and Ant-scripts used in this example are available here [../../../samples/cmp]. This example uses CMP. A similar example using bean-managed persistence (BMP) is available here Writing the Entity Bean The entity bean is a type of EJB that is persistent - or more precisely, it is able to store its state persistently. The state is often stored in a relational database, but can also be stored to other kinds of storage, e.g. directly to disk. Since entity beans are persistent, they are typically used to represent real-world objects like customers, equipment, items, etc. Entity beans support two different models; container managed persistence (CMP) and bean managed persistence (BMP). Using the CMP model, the Trifork Enterprise Application Server manages the persistency and the programmer does not have to write any code for persistence. This removes a layer of complexity and simplifies the implementation of entity beans. Using the BMP model, on the other side, the programmer has to write the code for persistence. This gives more control to the programmer and possibilities for optimizations, but it also makes it more complex to implement entity beans. This example focuses on the CMP model. 278

289 Chapter 29. Simple examples Enterprise JavaBeans are designed to be distributable and easy to maintain. Therefore, the implementation of an EJB is separated into different parts: The Remote Interface The Home Interface The Primary Key Class The Bean Class The remote interface defines the bean's exported methods that are available to other components. The home interface defines methods for controlling the bean's life cycle, i.e. methods for creating, removing, and finding beans. The primary key class is used to identify beans in the persistent storage. The bean class contains the implementation of the business logic including the methods declared in the home and remote interfaces. As of EJB 2.0, it is possible to declare and use two other kinds of interfaces - a local interface and a local home interface. These interfaces are used to support the local model, which couples objects more tightly than the remote model to reduce the performance overhead of the remote model. The local interface is not used in this example The Remote Interface The first thing to do is to write the remote interface (Sample.java [../../../samples/cmp/src/sample.ear/sample.jar/com/trifork/ejb/sample/sample.java]) which declares all methods that will be exported and available to other components. This interface must extend javax.ejb.ejbobject: Example Sample.java package com.trifork.ejb.sample; import javax.ejb.ejbobject; import java.rmi.remoteexception; public interface Sample extends EJBObject { public void setdata (String data) throws RemoteException; public String getdata () throws RemoteException; } All methods in this interface must throw java.rmi.remoteexception, since the entity bean will be executed remotely on the server side. The implementation of the methods declared in this interface are contained in the bean class. The reason for this separation is that it makes the beans distributable and maintainable. Distributable, since this method is compatible with remote method invocation. Maintainable, because the implementation is separated from the interface, which makes it easier to change the implementation The Home Interface Next, write the home interface (SampleHome.java / [../../../samplescmp/src/sample.ear/sample.jar/com/trifork/ejb/sample/samplehome.java]), which is used to control the life-cycle of the bean. During the life-cycle of a bean, the bean is created, searched, and removed - and this interface defines how this is done. Example SampleHome.java package com.trifork.ejb.sample; 279

290 Chapter 29. Simple examples import javax.ejb.ejbhome; import javax.ejb.createexception; import java.rmi.remoteexception; import javax.ejb.finderexception; import java.util.collection; public interface SampleHome extends EJBHome { public Sample create (int id, String data) throws CreateException, RemoteException; public Sample findbyprimarykey (SamplePK pk) throws FinderException, RemoteException; public Collection findallsamples () throws FinderException, RemoteException; } The home interface must extend javax.ejb.ejbhome, and it specifies the create and find methods that is used for creating and finding beans, respectively. The create method must throw javax.ejb.createexception and java.rmi.remoteexception. The find methods must throw javax.ejb.finderexception and java.rmi.remoteexception. The home interface may as well define a remove method, which is used to remove the bean from the persistent storage. The remove must throw javax.ejb.removeexception and java.rmi.remoteexception. The find methods in this example include findbyprimarykey and findallsamples. findbyprimarykey finds a Sample entity bean by using the primary key. findallsamples finds all Sample entity beans. The latter is specified via EJB-QL. The finder methods are not implemented in the bean class, as is the case for the other methods in this interface. The EJB-QL specification for this method is in the ejb-jar.xml deployment descriptor The Primary Key Class The Sample entity bean must have a primary key class (SamplePK.java [../../../samples/cmp/src/sample.ear/sample.jar/com/trifork/ejb/sample/samplepk.java]) that can be used to uniquely identify the entity bean in the persistent storage. The primary key class must implement java.io.serializable: Example SamplePK.java package com.trifork.ejb.sample; import java.io.serializable; public class SamplePK implements Serializable { public int id; public SamplePK () { this.id = 0; } public SamplePK (int id) { this.id = id; } public int hashcode () { return this.id; } public boolean equals (Object obj) { if (obj instanceof SamplePK) { return (id == ((SamplePK)obj).id); } return false; } } The primary key class defines one public field id that is used to identify Sample enterprise beans' state information in the persistent storage. The hashcode and equals methods ensure that the primary key evaluates properly when used, and these methods are required to be overridden The Bean Class The bean class (SampleBean.java [../../../samples/cmp/src/sample.ear/sample.jar/com/trifork/ejb/sample/samplebean.java]) implements the javax.ejb.entitybean interface and contains the implementation of the business logic of the enterprise bean: 280

291 Chapter 29. Simple examples Example SampleBean.java package com.trifork.ejb.sample; import javax.ejb.entitybean; import javax.ejb.entitycontext; public abstract class SampleBean implements EntityBean { // create methods public SamplePK ejbcreate (int id, String data) { setid(id); setdata(data); return null; } public void ejbpostcreate (int id, String data) {} // entitybean methods public void setentitycontext (EntityContext ctx) {} public void unsetentitycontext () {} public void ejbactivate () {} public void ejbpassivate () {} public void ejbload () {} public void ejbstore () {} public void ejbremove () {} // accessor methods public abstract void setdata (String data); public abstract String getdata (); public abstract void setid (int id); public abstract int getid (); } This class implements the methods declared in the remote interface and in the home interface. The first methods implemented are the methods related to the life-cycle of the bean. Create methods are declared in the ejbcreate and ejbpostcreate, which must contain matching arguments relative to the create method in the home interface. The ejbremove must be implemented and contain the code that removes the bean from the persistent storage. In this example, the remove is not implemented. This is also the case for ejbload and ejbstore, which loads and stores the state of the bean from and to the persistent storage, respectively. These methods are implemented by the Trifork Enterprise Application Server when using CMP and therefore left empty in the above implementation. As noticed, the ejbcreate must return a primary key, or more exactly; the primary key for this Sample entity bean. With CMP null is returned, as it is the container's responsibility to create the primary key. The remote interface specifies the exported methods of the EJB. In the bean class, these methods are implemented. The methods declared in the remote interface are getdata and setdata, which are called access methods. Besides these two access methods, the bean class contains access methods for the remaining persistent fields, in this case the id field. As of EJB 2.0, the class implementation of the entity bean using CMP must be declared abstract. Likewise, all accessor methods, e.g. getdata and setdata, must be declared abstract. As of EJB 2.0, container-managed instance fields are no longer declared explicitly in the source code as it was the case in previous EJB versions. Instance fields are now generated by the Trifork Enterprise Application Server. A few other methods must be implemented. These methods are setentitycontext, unsetentitycontext, ejbactivate, ejbpassivate. setentitycontext is an access method, indicating that the bean has been bound to a context. unsetentitycontext is called when the bean is about to be destroyed. This method can be used to release any resources the bean maintains. The ejbactivate and ejbpassivate are related to the pooling of objects. An object may be activated and passivated during its life-cycle. Passivation will make the bean available in the application server's pool of bean instances. Activation is performed during the reverse process. During activation and passivation, the ejbactivate and ejbpassivate may be used, e.g. to establish and release connections to resources. Because the sample entity bean does not make use of any resources that must be released, the imple281

292 Chapter 29. Simple examples mentation of these methods are left empty. ejbactivate and ejbpassivate are invoked by the EJB container and should not be called by the EJB programmer Writing the Servlet A servlet (SampleServlet.java [../../../samples/cmp/src/sample.ear/sample.war/web-inf/classes/com/trifork/web/sample/sampleservlet.java]) complements the web interface of this example. The Sample entity bean previously described is accessed through the SampleServlet: Example SampleServlet.java package com.trifork.web.sample;... public class SampleServlet extends HttpServlet { protected SampleHome samplehome = null; protected void doget (HttpServletRequest req, HttpServletResponse response) throws ServletException, IOException { PrintWriter writer = response.getwriter(); String curtime = new Date().toString(); String curclient = req.getremotehost(); Sample sampletime = null; Sample sampleclient = null; sampletime = establishsample (1, curtime); sampleclient = establishsample (2, curclient); // write response to be shown in browser writer.println("<html><body>"); writer.println("<h1>sampleservlet</h1><hr>"); writer.println("current time: "+curtime+"<br>"); writer.println("sample time: "+sampletime.getdata()+"<br>"); writer.println("sample client:"+sampleclient.getdata()+"<br>"); writer.println("<br><hr>"); // update the current time and client information sampletime.setdata (curtime); sampleclient.setdata (curclient); // write current sample content to the response to be shown in the browser try { Iterator i = getsamplehome().findallsamples().iterator(); int count = 0; while (i.hasnext()) { count++; Object obj = i.next(); Sample sample = (Sample)obj; writer.println(count + ". " + sample.getdata()+"<br>"); } } catch (Exception ex) { throw new ServletException ("Unable to show all samples"); } // write the end of the response to be shown in the browser writer.println("</body></html>"); } protected Sample establishsample (int id, String data) throws ServletException { Sample sample = null; try { sample = getsamplehome().findbyprimarykey (new SamplePK(id)); } catch (FinderException fe) { // do nothing } catch (RemoteException re) { throw new ServletException("Unable to find sample"); } try { if (sample == null) { 282

293 Chapter 29. Simple examples sample = getsamplehome().create(id, data); } } catch (Exception ex) { throw new ServletException ("Unable to find or create sample bean"); } return sample; } protected SampleHome getsamplehome () throws ServletException { if (this.samplehome == null) { try { javax.naming.context ctx = new javax.naming.initialcontext(); Object obj = ctx.lookup("ejb/sample"); this.samplehome = (SampleHome)javax.rmi.PortableRemoteObject.narrow(obj, SampleHom } catch (NamingException ne) { throw new ServletException ("Unable to lookup sample home"); } } return this.samplehome; } } The SampleServlet must extend javax.servlet.http.httpservlet. The servlet overrides the doget method, which is invoked when the servlet is accessed from a webbrowser by GET requests. The doget method first establishes two Sample entity beans, one named sampletime and one named sampleclient. The Sample entity beans are established by using the establishsample method. This method finds a given sample, and if the sample does not exist, it is created. The data stored in the samples during previous execution of the SampleServlet is written as output, and the data is updated. I.e. a new timestamp is stored, and the current client is stored. At the end of the doget method, the data of all samples are printed, by iterating the result of a findallsamples method call. The lookup of the Sample home is done in the getsamplehome method by using Java Naming and Directory Interface (JNDI). The Sample home is looked up using the JNDI-name ejb/sample. As will be shown later on, the trifork-app-conf.xml deployment descriptor binds the Sample entity bean to that JNDI-name. Notice that the getsamplehome only makes a JNDI-lookup one time. When the Sample home is looked up, it is stored in an instance field this.samplehome. Successive invocations of the getsamplehome will return this value instead of performing a new JNDI-lookup. This reduces the overhead of looking up. The static management of id used in the example is not generally advisable, since it makes use of hardcoded id values. The use of an EJB component dedicated to dynamic assignment of ids would be advisable, but it is too comprehensive to include in this small example Writing the Deployment Descriptors This example is organized in an enterprise archive (sample.ear [../../../samples/cmp/src/sample.ear]) containing two other archives - an archive (sample.jar [../../../samples/cmp/src/sample.ear/sample.jar]) containing the Sample entity bean and a web archive (sample.war [../../../samples/cmp/src/sample.ear/sample.war]) containing the SampleServlet. Each of these archives contains deployment descriptors that describes how their components are deployed on the Trifork Enterprise Application Server. These deployment descriptors are located as follows: Example Directory structure sample.ear/ sample.ear/meta-inf/ sample.ear/meta-inf/application.xml sample.ear/meta-inf/trifork-app-conf.xml sample.ear/sample.jar/ sample.ear/sample.jar/meta-inf/ sample.ear/sample.jar/meta-inf/ejb-jar.xml sample.ear/sample.war/ sample.ear/sample.war/web-inf/ sample.ear/sample.war/web-inf/web.xml sample.ear [../../../samples/cmp/src/sample.ear] contains 283 two deployment descriptors: application.xml

294 Chapter 29. Simple examples [../../../samples/cmp/src/sample.ear/meta-inf/application.xml] and trifork-app-conf.xml [../../../samples/cmp/src/sample.ear/meta-inf/trifork-app-conf.xml]. sample.jar [../../../samples/cmp/src/sample.ear/sample.jar] contains one deployment descriptor: ejb-jar.xml [../../../samples/cmp/src/sample.ear/sample.jar/meta-inf/ejb-jar.xml], and sample.war [../../../samples/cmp/src/sample.ear/sample.war] contains one deployment descriptor: web.xml [../../../samples/cmp/src/sample.ear/sample.war/web-inf/web.xml]. The trifork-app-conf.xml [../../../samples/cmp/src/sample.ear/meta-inf/trifork-app-conf.xml] is the only deployment descriptor specifically for the Trifork Enterprise Application Server. The remaining are general J2EE deployment descriptors. Successively, the deployment descriptors will be further described: The Application Deployment Descriptor The trifork-app-conf Deployment Descriptor The Ejb-jar Deployment Descriptor The Web Deployment Descriptor From the four deployment descriptors, only the trifork-app-conf.xml deployment descriptor and the ejb-jar.xml deployment descriptor are involved with the specification of container-managed persistence The Application Deployment Descriptor The application.xml [../../../samples/cmp/src/sample.ear/meta-inf/application.xml] deployment descriptor specifies which modules are contained in the enterprise archive. Example Application.xml <!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN' ' <application> <display-name>example1</display-name> <module> <web> <web-uri>sample.war</web-uri> <context-root>example1</context-root> </web> </module> <module> <ejb>sample.jar</ejb> </module> </application> In this example, two modules are contained - the web module containing the SampleServlet and the EJB module containing the Sample entity bean The trifork-app-conf Deployment Descriptor The trifork-app-conf.xml [../../../samples/cmp/src/sample.ear/meta-inf/trifork-app-conf.xml] deployment descriptor is the Trifork Enterprise Application Server deployment descriptor, which is a vendor-specific deployment descriptor. Example trifork-app-conf.xml <!DOCTYPE trifork-app-conf PUBLIC '-//Trifork Technologies//DTD Trifork System Descriptor1.0//EN ' 284

295 Chapter 29. Simple examples <trifork-app-conf> <web-app> <display-name>example1</display-name> <context-root>example1</context-root> </web-app> <enterprise-beans> <ejb> <ejb-name>ejb/sample</ejb-name> <jndi-name>ejb/sample</jndi-name> <cmp> <table-name>sample</table-name> <cmp-field> <field-name>id</field-name> <db-field-name>id</db-field-name> <db-field-type>int(5)</db-field-type> </cmp-field> <cmp-field> <field-name>data</field-name> <db-field-name>data</db-field-name> <db-field-type>varchar(255)</db-field-type> </cmp-field> <create-table-deploy>true</create-table-deploy> <delete-table-undeploy>true</delete-table-undeploy> </cmp> </ejb> </enterprise-beans> </trifork-app-conf> Generally, the elements in this deployment descriptor are quite similar to other vendor-specific deployment descriptors. E.g. this deployment descriptor binds enterprise beans to a JNDI name. In this example, the Sample entity bean referred through <ejb-name> is bound to the JNDI name ejb/sample. The <ejb-name> refers the specification given in the ejb-jar deployment descriptor. A special feature of the Trifork Enterprise Application Server is that it supports automatic creation and removal of database tables when applications are deployed and undeployed, respectively. This feature is expressed through the create-table-deploy and delete-table-undeploy elements. Accepted values in these elements are {True, False}. Another element for management of CMP is available, which is not shown in the deployment descriptor above. This element is is-modified-method and it specifies the name of a no-arg method on the CMP bean class with return type boolean. This method should return true only if the persistent fields of the CMP bean instance have been modified, and thus need to be stored The Ejb-jar Deployment Descriptor The ejb-jar.xml [../../../samples/cmp/src/sample.ear/sample.jar/meta-inf/ejb-jar.xml] is the deployment descriptor specifying the enterprise java beans in the archive. Example Ejb-jar.xml <!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' ' <ejb-jar> <enterprise-beans> <entity> <ejb-name>ejb/sample</ejb-name> <home>com.trifork.ejb.sample.samplehome</home> <remote>com.trifork.ejb.sample.sample</remote> <ejb-class>com.trifork.ejb.sample.samplebean</ejb-class> <persistence-type>container</persistence-type> <prim-key-class>com.trifork.ejb.sample.samplepk</prim-key-class> <reentrant>false</reentrant> <abstract-schema-name>sample</abstract-schema-name> <cmp-field> 285

296 Chapter 29. Simple examples <field-name>id</field-name> </cmp-field> <cmp-field> <field-name>data</field-name> </cmp-field> <query> <query-method> <method-name>findallsamples</method-name> <method-params></method-params> </query-method> <ejb-ql>select OBJECT(h) FROM sample AS h</ejb-ql> </query> </entity> </enterprise-beans> </ejb-jar> The <cmp-field> elements specify which fields are to be CMP managed by the Trifork Enterprise Application Server. Accessor methods to these fields must be declared in the entity bean class. The <query> element specifies how the findallsamples method declared in the home interface finds all samples. The specification is done using EJB-QL. First an abstract name for the table used for storing the samples is specified. This is done in the <abstract-schema-name>. The abstract name functions as a reference used in the EJB-QL query. The <query> element contains an element <query-method> that specifies the name and parameters of the find method (the findallsamples in this case) and the EJB-QL query statement. The actual EJB-QL query selects all Sample entity beans. Consult an EJB-QL reference manual for a more detailed description of the language and its syntax. The findbyprimarykey method declared in the home interface is not specified in this deployment descriptor, because this is the default find method. Since it is a default find method, it is not necessary to specify how it works The Web Deployment Descriptor The web.xml [../../../samples/cmp/src/sample.ear/sample.war/web-inf/web.xml] is the deployment descriptor specifying the web module in the enterprise archive. Example Web.xml <!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN' ' <web-app> <display-name>sample</display-name> <servlet> <servlet-name>sampleservlet</servlet-name> <display-name>sampleservlet</display-name> <servlet-class>com.trifork.web.sample.sampleservlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>sampleservlet</servlet-name> <url-pattern>sampleservlet</url-pattern> </servlet-mapping> <session-config> <session-timeout>1</session-timeout> </session-config> </web-app> In this example, the SampleServlet is specified and mapped to an url-pattern, specifying from where the servlet can be accessed from a webbrowser Building, deploying, and running the example An ANT build script has been provided for the example. This script can be used for building and deploying the example application. You can also deploy the application manually with the trifork command. 286

297 Chapter 29. Simple examples Building the example To build the archive, access the root of the example [../../../samples/cmp] in a command prompt. Next, edit the trifork.install.dir property in the build.xml file to reflect the server directory of server installation. Finally, build the archive by using the build.xml [../../../samples/cmp/src/build.xml] Ant script: Example Building the application <INSTALLATION_DIRECTORY>/server/ant/bin/ant build This will build the sample.ear [../../../samples/cmp/build/sample.ear] and place it in the build directory. This enterprise archive can then be deployed into the Trifork Enterprise Application Server Deploying the application Deploying the application requires tree steps: Creating a system container. Deploying the archive to the server. Creating a database table for the bean. Example Creating a system <INSTALLATION_DIRECTORY>/server/ant/bin/ant create-systemcontainer or <INSTALLATION_DIRECTORY>/domains/bin/trifork system create cmpexample This will create a system called cmpexample. If a system named cmpexample already exists, performing the create command will not affect the system or any existing applications inside it, but merely result in an error message. Next, deploy the archive to the server: Example Deploying the application <INSTALLATION_DIRECTORY>/server/ant/bin/ant deploy or <INSTALLATION_DIRECTORY>/domains/bin/trifork system archive deploy cmpexample <INSTALLATION_DIREC This will deploy the sample.ear to the cmpexample system Running the example If the output of this command is a success, then open a webbrowser and access the example at this URL: This concludes the example. Try performing some experiments by modifying the source code, and repeat the build, deploy and run procedure described above, and see that your changes are reflected in the running application. 287

298 Chapter 29. Simple examples Entity Bean using BMP This example shows how to construct and deploy an enterprise entity bean using bean-managed persistence (BMP) in the Trifork Enterprise Application Server. When using bean-managed persistence it is the responsibility of the bean to manage the persistence, which is typically done using a database. This is also the case for this example. The example shows how to write an entity bean (Sample) that can store a string persistently using beanmanaged persistence. The example shows how the Sample entity bean can be accessed from a servlet (SampleServlet). The SampleServlet uses the Sample entity bean to store the timestamp of the last access to the Sample entity, and the SampleServlet then renders this timestamp along with the current time as output. The example is divided into the following parts, which are described successively: Writing the Entity Bean Writing the Servlet Writing the Deployment Descriptors Building, deploying, and running the example Source code, deployment descriptors, and Ant-scripts used in this example are available here [../../../samples/bmp]. This example uses BMP. A similar example using container-managed persistence (CMP) is available here Writing the Entity Bean The entity bean is a type of EJB that is persistent - or more precisely, it is able to store its state persistently. The state is often stored in a relational database, but can also be stored to other kinds of storage, e.g. directly to disk. Since entity beans are persistent, they are typically used to represent real-world objects like customers, equipment, items, etc. Entity beans support two different models; container managed persistence (CMP) and bean managed persistence (BMP). Using the CMP model, the Trifork Enterprise Application Server manages the persistency and the programmer does not have to write any code for persistence. This removes a layer of complexity and simplifies the implementation of entity beans. Using the BMP model, on the other side, the programmer has to write the code for persistence. This gives more control to the programmer and possibilities for optimizations, but it also makes it more complex to implement entity beans. This example focuses on the BMP mode. Enterprise JavaBeans are designed to be distributable and easy to maintain. Therefore, the implementation of an EJB is separated into different parts: The Remote Interface The Home Interface The Primary Key Class The Bean Class The remote interface defines the bean's exported methods that are available to other components. The home interface defines methods for controlling the bean's life cycle, i.e. methods for creating, removing, and finding beans. The primary key class is used to identify beans in the persistent storage. The bean class contains the implementation of the business logic including the methods declared in the home and remote interfaces. As of EJB 2.0, it is possible to declare and use two other kinds of interfaces - a local interface and a local home 288

299 Chapter 29. Simple examples interface. These interfaces are used to support the local model, which couples objects more tightly than the remote model to reduce the performance overhead of the remote model. The local interface is not used in this example The Remote Interface The first thing to do is to write the remote interface (Sample.java [../../../samples/bmp/src/sample.ear/sample.jar/com/trifork/ejb/sample/sample.java]) which declares all methods that will be exported and available to other components. This interface must extend javax.ejb.ejbobject: Example Sample.java package com.trifork.ejb.sample; import javax.ejb.ejbobject; import java.rmi.remoteexception; public interface Sample extends EJBObject { public void setdata (String data) throws RemoteException; public String getdata () throws RemoteException; } All methods in this interface must throw java.rmi.remoteexception, since the entity bean will be executed remotely on the server side. The implementation of the methods defined in this interface are contained in the bean class. The reason for this seperation is that it makes the beans distributable and maintainable. Distributable, since this method is compatible with remote method invocation. Maintainable, because the implementation is separated from the interface, which makes it easier to change the implementation The Home Interface Next, write the home interface (SampleHome.java [../../../samples/bmp/src/sample.ear/sample.jar/com/trifork/ejb/sample/samplehome.java]), which is used to control the life-cycle of the bean. During the life-cycle of a bean, the bean is created, searched, and removed and this interface defines how this is done. Example SampleHome.java package com.trifork.ejb.sample; import javax.ejb.ejbhome; import javax.ejb.createexception; import java.rmi.remoteexception; import javax.ejb.finderexception; public interface SampleHome extends EJBHome { public Sample create (int id, String data) throws CreateException, RemoteException; public Sample findbyprimarykey (SamplePK pk) throws FinderException, RemoteException; } The home interface must extend javax.ejb.ejbhome, and it declares create and find methods. The create methods must throw javax.ejb.createexception and java.rmi.remoteexception. The find methods must throw javax.ejb.finderexception and java.rmi.remoteexception. The home interface may as well define a remove method, which is used to remove the bean from the persistent storage. The remove must throw javax.ejb.removeexception and java.rmi.remoteexception The Primary Key Class The Sample entity bean must have a primary key class (SamplePK.java [../../../samples/bmp/src/sample.ear/sample.jar/com/trifork/ejb/sample/samplepk.java]) that can be used to uniquely identify the entity bean in the database. The primary key class must implement java.io.serializable: 289

300 Chapter 29. Simple examples Example SamplePK.java package com.trifork.ejb.sample; import java.io.serializable; public class SamplePK implements Serializable { public int id; public SamplePK () { this.id = 0; } public SamplePK (int id) { this.id = id; } public int hashcode () { return this.id; } public boolean equals (Object obj) { if (obj instanceof SamplePK) { return (id == ((SamplePK)obj).id); } return false; } } The primary key class defines one public field id that is used to identify Sample enterprise beans' state information in the database. The hashcode and equals methods ensure that the primary key evaluates properly when used, and these methods are required to be overridden The Bean Class The bean class (SampleBean.java [../../../samples/bmp/src/sample.ear/sample.jar/com/trifork/ejb/sample/samplebean.java]) implements the javax.ejb.entitybean interface and contains the implementation of the business logic of the enterprise bean: Example SampleBean.java package com.trifork.ejb.sample; import java.sql.*; import javax.ejb.*; import javax.naming.*; import javax.sql.datasource; public class SampleBean implements EntityBean { // fields protected EntityContext ctx = null; // persistent fields protected int id; protected String data; // accessor methods public void setdata (String data) { this.data = data; } public String getdata () { return this.data; } public void setid (int id) { this.id = id; } public int getid () { return this.id; } // contextual methods public void setentitycontext (EntityContext ctx) { this.ctx = ctx; } public void unsetentitycontext () { this.ctx = null; } public EntityContext getentitycontext () { return this.ctx; } // activation methods public void ejbactivate () {} public void ejbpassivate () {} 290

301 Chapter 29. Simple examples... } The entity bean declares fields that are to be handled persistently. The fields are id and data. The entity bean class implements the methods declared in the remote interface. These are the getdata and setdata methods, which are access methods like the getid and setid methods. The bean class is required to implement a number of methods. Some of the required methods are shown in the source code above - but many others exist, which are concerned with the management of persistence. These methods include ejbcreate, ejbpostcreate, ejbload, ejbstore, ejbremove and ejbfindbyprimarykey. They will be described successively. The ejbcreate is called when a Sample entity bean is to be created. This method must throw javax.ejb.createexception: Example Create methods public SamplePK ejbcreate (int id, String data) throws CreateException { // validate parameters if ((id < 1) (data == null)) { throw new CreateException("Invalid parameters"); } // set state setid(id); setdata(data); // create tuple in database Connection con = null; PreparedStatement ps = null; SamplePK pk = null; try { con = getconnection(); ps = con.preparestatement("insert INTO sample (id, data) values (?,?)"); ps.setint(1,id); ps.setstring(2,data); if (ps.executeupdate()!= 1) { throw new CreateException("Cannot add Sample to database"); } pk = new SamplePK(id); } catch (SQLException se) { throw new CreateException("Cannot add Sample to database"); } finally { try { if (ps!= null) { ps.close(); }} catch (SQLException se) {} try { if (con!= null) { con.close(); }} catch (SQLException se) {} } return pk; } public void ejbpostcreate (int id, String data) {} The entity bean must have a ejbpostcreate method with matching parameters relative to the create method. During create, the bean cannot access its own primary key and EJB object, but this can be done during ejbpostcreate. This might be usefull for initialization. But this is not the case in our example. Next required method is the ejbload method, which is called when the Sample entity bean must load its state information from the database. This method must throw javax.ejb.ejbexception. Example The ejbload method public void ejbload () throws EJBException{ SamplePK pk = (SamplePK)getEntityContext().getPrimaryKey(); Connection con = null; PreparedStatement ps = null; ResultSet rs = null; try { con = getconnection(); 291

302 Chapter 29. Simple examples ps = con.preparestatement("select data FROM sample WHERE id=?"); ps.setint(1,pk.id); rs = ps.executequery(); if (rs.next()) { String data = rs.getstring(1); setdata(data); setid(pk.id); } else { throw new EJBException ("Cannot load Sample"); } } catch (SQLException se) { throw new EJBException("Cannot load Sample from database"); } finally { try { if (rs!= null) { rs.close(); }} catch (SQLException se) {} try { if (ps!= null) { ps.close(); }} catch (SQLException se) {} try { if (con!= null) { con.close(); }} catch (SQLException se) {} } } ejbload access the database and makes an SQL-query that selects the actual SampleBean. The SampleBean is identified by its primary key. The data from the database is loaded into the field of the SampleBean by using its accessor methods. The SampleBean is required to be able to store its state into the database. This is done in the ejbstore method. Like the ejbload, this method must throw javax.ejb.ejbexception. Example The ejbstore method public void ejbstore () throws EJBException { Connection con = null; PreparedStatement ps = null; try { con = getconnection(); ps = con.preparestatement("update sample SET data=? WHERE id=?"); ps.setstring(1, getdata()); ps.setint(2, getid()); if (ps.executeupdate()!= 1) { throw new EJBException ("Cannot store Sample in database"); } } catch (SQLException se) { throw new EJBException("Cannot store Sample from database"); } finally { try { if (ps!= null) { ps.close(); }} catch (SQLException se) {} try { if (con!= null) { con.close(); }} catch (SQLException se) {} } } Like ejbload, this method acquires a database connection and makes an SQL-query into it. This SQL-query updates the data in the database that represents the actual SampleBean. It is also required that a bean-managed entity bean must be able to remove the data that represents itself from the database. This is done through the ejbremove method, which also must throw javax.ejb.ejbexception. Example The ejbremove method public void ejbremove () throws EJBException { Connection con = null; PreparedStatement ps = null; try { con = getconnection(); ps = con.preparestatement("delete FROM sample WHERE id=?"); ps.setint(1,getid()); if (ps.executeupdate()!= 1) { throw new EJBException ("Cannot remove Sample in database"); 292

303 Chapter 29. Simple examples } } catch (SQLException se) { throw new EJBException("Cannot remove Sample from database"); } finally { try { if (ps!= null) { ps.close(); }} catch (SQLException se) {} try { if (con!= null) { con.close(); }} catch (SQLException se) {} } } The ejbremove is implemented like ejbload and ejbstore by updating the database by an SQL-query. The Sample bean must implement the find methods declared in the remote interface. In this example only one find method is declared, and it must throw javax.ejb.finderexception Example The ejbfindbyprimarykey method public SamplePK ejbfindbyprimarykey (SamplePK pk) throws FinderException { Connection con = null; PreparedStatement ps = null; ResultSet rs = null; SamplePK result = null; try { con = getconnection(); ps = con.preparestatement("select * FROM sample WHERE id=?"); ps.setint(1,pk.id); rs = ps.executequery(); if (rs.next()) { result = pk; } else { throw new ObjectNotFoundException ("Cannot find Sample in database"); } } catch (SQLException se) { throw new EJBException("Cannot find Sample from database"); } finally { try { if (rs!= null) { rs.close(); }} catch (SQLException se) {} try { if (ps!= null) { ps.close(); }} catch (SQLException se) {} try { if (con!= null) { con.close(); }} catch (SQLException se) {} } return result; } The implementation of the find method in this class matches most of the signature of the find method from the remote interface. Method name and method arguments must be equivalent, but the return type differs. Where the remote interface returns a SampleBean instance, this method must return an instance of the SamplePK. The ejbcreate, ejbload, ejbstore, ejbremove, ejbfindbyprimarykey methods all make use of the database. The connection to the database is acquired using the getconnection method: Example The getconnection method protected Connection getconnection () throws SQLException { try { Context ctx = new InitialContext(); DataSource ds = (DataSource) ctx.lookup("jdbc/triforkdb"); return ds.getconnection(); } catch (NamingException ne) { throw new EJBException ("Cannot get database connection"); } } This method looks up a resource through the Java Naming and Directory Interface (JNDI). The resource is a database connection that has been bound to JNDI name jdbc/triforkdb. 293

304 Chapter 29. Simple examples Two other methods must be implemented. These methods are ejbactivate and ejbpassivate. These methods are related to the pooling of objects. An object may be activated and passivated during its life-cycle. Passivation will make the bean available in the application server's pool of bean instances. Activation is performed during the reverse process. During activation and passivation, the ejbactivate and ejbpassivate may be used e.g. to establish and release connections to resources. Because the sample entity bean releases the database connection straight after the query has been done and no other resources are maintained, the implementation of these methods are left empty. ejbactivate and ejbpassivate are invoked by the EJB container and should not be called by the EJB programmer Writing the Servlet A servlet ( SampleServlet.java [../../../samples/bmp/src/sample.ear/sample.war/web-inf/classes/com/trifork/web/sample/sampleservlet.java]) complements the web interface of this example. The Sample entity bean previously described is accessed through the SampleServlet: Example SampleServlet.java package com.trifork.web.sample; import import import import import import import import com.trifork.ejb.sample.*; javax.servlet.*; javax.servlet.http.*; javax.ejb.finderexception; java.rmi.remoteexception; java.io.ioexception; java.io.printwriter; java.util.date; public class SampleServlet extends HttpServlet { protected void doget (HttpServletRequest req, HttpServletResponse response) throws ServletExc { PrintWriter writer = response.getwriter(); String curtimestr = new Date().toString(); Sample sample = null; SampleHome samplehome = null; // if sample with id=1 does not exist, then create sample with this id try { javax.naming.context ctx = new javax.naming.initialcontext(); Object obj = ctx.lookup("ejb/sample"); samplehome = (SampleHome)javax.rmi.PortableRemoteObject.narrow(obj, SampleHome.class) } catch (Exception ex) { throw new ServletException ("Unable to lookup sample home"); } try { sample = samplehome.findbyprimarykey (new SamplePK(1)); } catch (FinderException fe) { // do nothing } catch (RemoteException re) { throw new ServletException ("Unable to find sample bean"); } try { if (sample == null) { sample = samplehome.create(1, curtimestr); } } catch (Exception ce) { throw new ServletException ("Unable to create sample bean"); } // write response to be shown in browser writer.println("<html><body>"); writer.println("<h1>sampleservlet</h1><hr>"); writer.println("current time: "+curtimestr+"<br>"); writer.println("sample time: "+sample.getdata()+"<br>"); writer.println("<br>"); 294

305 Chapter 29. Simple examples writer.println("</body></html>"); // sets the current time as the data of the sample sample.setdata (curtimestr); } } The SampleServlet must extend javax.servlet.http.httpservlet. The servlet overrides the doget method, which is invoked when the servlet is accessed from a webbrowser by GET requests. The doget method first examines whether or not a Sample entity bean with id=1 exists. If this is the case, the existing entity bean is given a new timestamp. If the entity bean does not exist, a Sample entity bean is created with a new timestamp. During management of the Sample entity bean, HTML code is generated and returned as output. The HTML code includes information about the current time and the previous timestamp of the Sample entity bean. The static management of id used in the example is not generally advisable, since it makes use of hardcoded id values. The use of an EJB component dedicated to dynamic assignment of ids would be advisable, but it is too comprehensive to include in this small example. The lookup of the Sample home is done by using Java Naming and Directory Interface (JNDI). The Sample home is looked up using the JNDI-name ejb/sample. As will be shown later on, the trifork-app-conf.xml deployment descriptor binds the Sample entity bean to that JNDI-name Writing the Deployment Descriptors This example is organized in an enterprise archive (sample.ear [../../../samples/bmp/src/sample.ear]) containing two other archives - an archive (sample.jar [../../../samples/bmp/src/sample.ear/sample.jar]) containing the Sample entity bean and a web archive (sample.war [../../../samples/bmp/src/sample.ear/sample.war]) containing the SampleServlet. Each of these archives contains deployment descriptors that describes how their components are deployed on the Trifork Enterprise Application Server. These deployment descriptors are located as follows: Example Directory Structure sample.ear/ sample.ear/meta-inf/ sample.ear/meta-inf/application.xml sample.ear/meta-inf/trifork-app-conf.xml sample.ear/sample.jar/ sample.ear/sample.jar/meta-inf/ sample.ear/sample.jar/meta-inf/ejb-jar.xml sample.ear/sample.war/ sample.ear/sample.war/web-inf/ sample.ear/sample.war/web-inf/web.xml sample.ear [../../../samples/bmp/src/sample.ear] contains two deployment descriptors: application.xml [../../../samples/bmp/src/sample.ear/meta-inf/application.xml] and trifork-app-conf.xml [../../../samples/bmp/src/sample.ear/meta-inf/trifork-app-conf.xml]. sample.jar [../../../samples/bmp/src/sample.ear/sample.jar] contains one deployment descriptor: ejb-jar.xml [../../../samples/bmp/src/sample.ear/sample.jar/meta-inf/ejb-jar.xml], and sample.war [../../../samples/bmp/src/sample.ear/sample.war] contains one deployment descriptor: web.xml [../../../samples/bmp/src/sample.ear/sample.war/web-inf/web.xml]. The trifork-app-conf.xml [../../../samples/bmp/src/sample.ear/meta-inf/trifork-app-conf.xml] is the only deployment descriptor specific for the Trifork Enterprise Application Server, the remaining are general J2EE deployment descriptors. Successively the deployment descriptors will be described further: The Application Deployment Descriptor The trifork-app-conf Deployment Descriptor 295

306 Chapter 29. Simple examples The Ejb-jar Deployment Descriptor The Web Deployment Descriptor From the four deployment descriptors, only the trifork-app-conf.xml deployment descriptor and the ejb-jar.xml deployment descriptor are involved with the specification of bean-managed persistence The Application Deployment Descriptor The application.xml [../../../samples/bmp/src/sample.ear/meta-inf/application.xml] deployment descriptor specifies which modules are contained in the enterprise archive. Example Application.xml <!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN' ' <application> <display-name>example2</display-name> <module> <web> <web-uri>sample.war</web-uri> <context-root>example2</context-root> </web> </module> <module> <ejb>sample.jar</ejb> </module> </application> In this example two modules are contained - the web module containing the SampleServlet and the EJB module containing the Sample entity bean The trifork-app-conf Deployment Descriptor The trifork-app-conf.xml [../../../samples/bmp/src/sample.ear/meta-inf/trifork-app-conf.xml] deployment descriptor is the Trifork Enterprise Application Server deployment descriptor, which is a vendor-specific deployment descriptor. Example trifork-app-conf.xml <!DOCTYPE trifork-app-conf PUBLIC '-//Trifork Technologies//DTD Trifork System Descriptor1.0//EN ' <trifork-app-conf> <web-app> <display-name>example2</display-name> <context-root>example2</context-root> </web-app> <enterprise-beans> <ejb> <ejb-name>ejb/sample</ejb-name> <jndi-name>ejb/sample</jndi-name> <resource-ref> <res-ref-name>jdbc/triforkdb</res-ref-name> <jndi-name>jdbc/triforkdb</jndi-name> </resource-ref> </ejb> </enterprise-beans> </trifork-app-conf> The trifork deployment descriptor specifies that the SampleBean makes use of a resource through the re296

307 Chapter 29. Simple examples source-ref>. This resource is the database, and the JNDI-name of the database is given in this deployment descriptor. Inside the resource-ref a res-ref-name is given, which is used as reference in the deployment descriptors and the source code. A mapping occurs between the res-ref-name and the jndi-name when performing a lookup. The res-ref-name used e.g. in the source code in the getconnection method in the bean class is mapped to jdbc/triforkdb as specified in the jndi-name element. In this example, the two references are identical, but the jndi-name could be different from the res-ref-name The Ejb-jar Deployment Descriptor The ejb-jar.xml [../../../samples/bmp/src/sample.ear/sample.jar/meta-inf/ejb-jar.xml] is the deployment descriptor specifying the enterprise java beans in the archive. Example Ejb-jar.xml <!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' ' <ejb-jar> <enterprise-beans> <entity> <ejb-name>ejb/sample</ejb-name> <home>com.trifork.ejb.sample.samplehome</home> <remote>com.trifork.ejb.sample.sample</remote> <ejb-class>com.trifork.ejb.sample.samplebean</ejb-class> <persistence-type>bean</persistence-type> <prim-key-class>com.trifork.ejb.sample.samplepk</prim-key-class> <reentrant>false</reentrant> <resource-ref> <res-ref-name>jdbc/triforkdb</res-ref-name> <res-type>javax.sql.datasource</res-type> <res-auth>container</res-auth> </resource-ref> </entity> </enterprise-beans> </ejb-jar> The database resource specified in the Trifork Deployment Descriptor is used by the Sample entity bean. This is specified via the <resource-ref> element. In this element the type of the resource and the authentication method are specified. Valid values for the <res-auth> are {Application, Container}. These values specify whether the bean code signs on programmatically to the resource manager, or the EJB Container will sign on to the resource manager on behalf of the enterprise bean. In the latter case, the EJB Container uses information that is supplied by the jdbcpool.xml deployment descriptor used by the Trifork Enterprise Application Server. The jdbcpool.xml deployment descriptor is located in / <TRIFORK_INSTALL_DIR>servers/default/config/jdbcpool.xml The Web Deployment Descriptor The web.xml [../../../samples/bmp/src/sample.ear/sample.war/web-inf/web.xml] is the deployment descriptor specifying the web module in the enterprise archive. Example Web.xml <!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN' ' <web-app> <display-name>sample</display-name> <servlet> <servlet-name>sampleservlet</servlet-name> <display-name>sampleservlet</display-name> <servlet-class>com.trifork.web.sample.sampleservlet</servlet-class> </servlet> <servlet-mapping> <servlet-name>sampleservlet</servlet-name> <url-pattern>sampleservlet</url-pattern> 297

308 Chapter 29. Simple examples </servlet-mapping> <session-config> <session-timeout>1</session-timeout> </session-config> </web-app> In this example, the SampleServlet is specified and mapped to an url-pattern, specifying from where the servlet can be accessed from a webbrowser Building, deploying, and running the example An ANT build script has been provided for the example. This script can be used for building and deploying the example application. You can also deploy the application manually with the trifork command Building the example To build the archive, access the root of the example [../../../samples/bmp] in a command prompt. Next, edit the trifork.install.dir in the build.xml file property to reflect the server directory of server installation. Finally, build the archive by using the build.xml [../../../samples/bmp/src/build.xml] Ant script: Example Building the application <INSTALLATION_DIRECTORY>/server/ant/bin/ant build This will build the sample.ear [../../../samples/bmp/build/sample.ear] and place it in the build directory. This enterprise archive can then be deployed into the Trifork Enterprise Application Server Deploying the application Deploying the application requires tree steps: Creating a system container. Deploying the archive to the server. Creating a database table for the bean. Example Creating a system <INSTALLATION_DIRECTORY>/server/ant/bin/ant create-systemcontainer or <INSTALLATION_DIRECTORY>/domains/bin/trifork system create bmpexample This will create a system called bmpexample. If a system named bmpexample already exists, performing the create command will not affect the system or any existing applications inside it, but merely result in an error message. Next, deploy the archive to the server: Example Deploying the archive <INSTALLATION_DIRECTORY>/server/ant/bin/ant deploy 298

309 Chapter 29. Simple examples or <INSTALLATION_DIRECTORY>/domains/bin/trifork system archive deploy bmpexample <INSTALLATION_DIREC This will deploy the sample.ear to the bmpexample system. Note, that if the cmpexample is deployed, this will cause a JNDI problem, since both beans are tied to the same name in the global name space. In this case issue the following command: <INSTALLATION_DIRECTORY>/domains/bin/trifork system remove cmpexample Because the example uses BMP and a database to store the data, we must ensure that database tables are created. This final step of the deployment is handled by the Ant script: Example Creating tables <INSTALLATION_DIRECTORY>/server/ant/bin/ant create-table Running the example Now open a webbrowser and access the example at this URL: where you should be able to see the SampleServlet. This concludes the example. Try performing some experiments by modifying the source code, and repeat the build, deploy and run procedure described above, and see that your changes are reflected in the running application Cleaning up If you want to remove the example, the Ant script can remove the database table used in this example: Example Removing tables <INSTALLATION_DIRECTORY>/server/ant/bin/ant remove-table Session Bean and JSP This example shows how to write and deploy a (stateless) session bean in the Trifork Enterprise Application Server. It also shows how to access the session bean from a Java Server Page (JSP). This example shows how to construct a session bean (TempConverter) that can convert temperatures from Celsius to Fahrenheit and vice versa. The example shows how the TempConverter session bean can be accessed from a Java Server Page (JSP) through a JavaBean wrapper (TempConverterWrapper). The example is divided into the following parts: Writing the Session Bean Writing the JSP page Writing a JavaBean wrapper Writing the Deployment Descriptors Building, deploying, and running the example 299

310 Chapter 29. Simple examples Source code, deployment descriptors, and Ant-scripts used in this example are available here [../../../samples/stateless] Writing the Session Bean The session bean is a type of EJB that can be seen as a collection of functionality. Session beans are transient and not designed to be persistent. Typically, a session bean is used for modelling processes, services, or client side sessions. Session beans support two different models; stateless and statefull session beans. Stateless session beans are lightweight, scalable components that are used to model services that do not maintain conversational state. Statefull session beans on the other hand do maintain conversational state. E.g. during shopping, a commonly used methaphor is the shopping cart. You may browse information about different items, and during your shopping session you fill items into the shopping cart. When finished shopping, the items must be paid and delivery information given. The conversational state is e.g. the state of the customer (shopping, paying etc.). This example focuses on the stateless session bean model. Enterprise JavaBeans are designed to be distributable and easy to maintain. Therefore, the implementation of an EJB is separated into different parts: The Remote Interface The Home Interface The Bean Class The remote interface defines the bean's exported methods that are available to other components. The home interface defines methods for controlling the bean's life cycle, i.e. methods for creating and finding beans. The bean class contains the implementation of the business logic including the methods declared in the home and remote interfaces. The primary key class used in entity beans to identify beans are not used in session beans, since session beans are transient and not persistent. As of EJB 2.0, it is possible to declare and use two other kinds of interfaces - a local interface and a local home interface. These interfaces are used to support the local model, which couples objects more tightly than the remote model to reduce the performance overhead of the remote model. The local interface is not used in this example The Remote Interface The remote interface (TempConverter.java [../../../samples/stateless/src/sample.ear/sample.jar/com/trifork/ejb/tempconverter/tempconverter.java]) declares all exported methods of the session bean. The TempConverter remote interface must extend javax.ejb.ejbobject: Example TempConverter.java package com.trifork.ejb.tempconverter; import java.rmi.remoteexception; public interface TempConverter extends javax.ejb.ejbobject { public double convertfahrenheittocelsius (double fahrenheit) throws RemoteException; public double convertcelsiustofahrenheit (double celsius) throws RemoteException; } All methods in this interface must throw java.rmi.remoteexception, since the entity bean will be executed remotely on the server side. The implementation of the methods defined in this interface is contained in the bean class. The reason for this separation is that it makes the beans distributable and easily maintainable. Distributable, because it fits the remote method invocation (RMI) model. Maintainable, because the implementation is separated from the interface, which makes it easier to change the implementation. 300

311 Chapter 29. Simple examples The Home Interface The home interface (TempConverterHome.java [../../../samples/stateless/src/sample.ear/sample.jar/com/trifork/ejb/tempconverter/tempconverterhome.java]) is used to create the session bean. This interface must extend javax.ejb.ejbhome and must contain a create method with no arguments: Example TempConverterHome.java package com.trifork.ejb.tempconverter; import java.rmi.remoteexception; import javax.ejb.createexception; public interface TempConverterHome extends javax.ejb.ejbhome { public TempConverter create () throws RemoteException, CreateException; } create methods must throw javax.ejb.createexception and java.rmi.remoteexception. The create method must have no arguments, because a stateless session bean does not maintain any conversational state and parameters for the creation should not be necessary The Bean Class The bean class (TempConverterBean.java [../../../samples/stateless/src/sample.ear/sample.jar/com/trifork/ejb/tempconverter/tempconverterbean.java]) implements the javax.ejb.sessionbean interface and contains the implementation of the business logic of the enterprise bean: Example TempConverterBean.java package com.trifork.ejb.tempconverter; public class TempConverterBean implements javax.ejb.sessionbean { public double convertfahrenheittocelsius (double fahrenheit) { return (fahrenheit-32)*5/9; } public double convertcelsiustofahrenheit (double celsius) { return (celsius*9/5)+32; } public void ejbcreate () {} public void ejbremove () {} public void ejbactivate () {} public void ejbpassivate () {} public void setsessioncontext (javax.ejb.sessioncontext ctx) {} } The bean class must implement the life-cycle methods ejbcreate and ejbremove. ejbcreate is invoked, when the session bean is created. ejbremove is invoked, when the session bean is about to be destroyed. These methods can be used e.g. to establish and release connections to resources, respectively. Since this example does not use any such resources these methods are left empty. Stateless session beans are not subject to passivation and activation, hence ejbactivate and ejbpassivate will always be left empty, when implementing this type of session bean. setsessioncontext is an accessor method for the context of the session bean. Since the context is not used by the session bean, this method is left empty Writing the JSP page A JSP page (TempConverter.jsp [../../../samples/stateless/src/sample.ear/sample.war/tempconverter.jsp]) complements the web interface of this example. The TempConverter session bean previously described is accessed 301

312 Chapter 29. Simple examples through the JSP page: Example TempConverter.jsp page language="java" import="java.rmi.remoteexception" %> <jsp:usebean id="tempconverter" class="com.trifork.web.tempconverter.tempconverterwrapper" scope= <jsp:setproperty name="tempconverter" property="*"/> </jsp:usebean> <html> <h1>temperature Converter</h1> <hr> <form action="tempconverter.jsp" method="post" > <u>select temperature type:</u><br> <input type="radio" name="temp_type" value="celsius">celsius<br> <input type="radio" name="temp_type" value="fahrenheit">fahrenheit<br> <br> Temperature:<input size=24 name=temperature class="mainformtext"> <input type="submit" name="submit" value="convert" class="submitformtext"><br> </form> <hr><br> <% String temperature = request.getparameter("temperature"), temperaturetype = request.getparameter("temp_type"); if (temperature!= null && temperaturetype!= null) { if (temperaturetype.equals("celsius")) { try { double res = tempconverter.convertcelsiustofahrenheit (temperature); out.write(temperature + "&#176 celsius = " + res + "&#176 fahrenheit"); } catch (RemoteException re) {} } else { try { double res = tempconverter.convertfahrenheittocelsius (temperature); out.write(temperature + "&#176 fahrenheit = " + res + "&#176 celsius"); } catch (RemoteException re) {} } } %> </html> The JSP page interacts with the TempConverter session bean through a JavaBean wrapper. The reason for using a JavaBean wrapper is to separate presentation logic from business logic to make it easier to maintain and change the separate parts independently. The <jsp:usebean> element specifies that the JSP page associates the TempConverterWrapper by the name tempconverter. Then an html <form> is declared. This form specifies that all inputs, i.e. the temperature and the type of temperature (Celsius or Fahrenheit), are posted to this JSP page. At the end of the JSP page, the convertions are performed and results outputted. Depending on the given type of temperature inputted, the conversion is done invoking either convertcelsiustofahrenheit or convertfahrenheittocelsius. The invocation of the method performing the conversion is done using the tempconverter identifier. This identifier was bound to the TempConverterWrapper in the top of the JSP page Writing the JavaBean Wrapper The JSP page must interact with the TempConverter session bean. This interaction can be done through a JavaBean wrapper (TempConverterWrapper.java r/ WEBINF/ classes/ 302

313 Chapter 29. Simple examples ). The purpose of the TempConverterWrapper is to encapsulate the code that is not a part of the presentation logic nor the business logic. This is e.g. lookup of the TempConverter home and conversion of arguments between the two tiers. Example TempConverterWrapper.java package com.trifork.web.tempconverter; import com.trifork.ejb.tempconverter.*; import java.rmi.remoteexception; public class TempConverterWrapper { public double convertfahrenheittocelsius (String fahrenheit) throws RemoteException { double temp = Double.parseDouble(fahrenheit); return convertfahrenheittocelsius(temp); } public double convertfahrenheittocelsius (double fahrenheit) throws RemoteException { return gettempconverter().convertfahrenheittocelsius(fahrenheit); } public double convertcelsiustofahrenheit (String celsius) throws RemoteException { double temp = Double.parseDouble(celsius); return gettempconverter().convertcelsiustofahrenheit(temp); } public double convertcelsiustofahrenheit (double celsius) throws RemoteException { return gettempconverter().convertcelsiustofahrenheit(celsius); } protected TempConverter gettempconverter () { TempConverter tempconverter = null; try { javax.naming.context ctx = new javax.naming.initialcontext(); Object obj = ctx.lookup("ejb/tempconverter"); TempConverterHome tempconverterhome = (TempConverterHome)javax.rmi.PortableRemoteObje tempconverter = tempconverterhome.create(); } catch (Exception ex) { ; } return tempconverter; } } The lookup of the TempConverter home is done in the gettempconverter method by using Java Naming and Directory Interface (JNDI). The TempConverter home is looked up using the JNDI-name ejb/tempconverter. As seen in the trifork-app-conf.xml deployment descriptor, the TempConverter bean is bound to that JNDIname. The methods for performing the temperature conversion are wrapping the methods on the TempConverter session bean. RemoteException is thrown from these methods, ensuring that exceptions thrown during interaction with the session bean are passed on. It is optional if wrapper methods throw RemoteException. The wrapper contains overloaded methods of both conversion methods, so that each conversion method can be invoked with argument type String or double. The TempConverter bean provides conversion methods that take double as argument, and arguments obtained from the JSP page are of type String. The overloaded conversion takes care of the type casting from String to double Writing the Deployment Descriptors This example is organised in an enterprise archive (sample.ear [../../../samples/stateless/src/sample.ear]) containing two other archives - an archive (sample.jar [../../../samples/stateless/src/sample.ear/sample.jar]) containing the Sample entity bean and a web archive (sample.war [../../../samples/stateless/src/sample.ear/sample.war]) containing the JSP page and the JavaBean wrapper. Each of these archives contains deployment descriptors that describe how their components are deployed on the Trifork Enterprise Application Server. These deployment descriptors are located as follows: 303

314 Chapter 29. Simple examples Example Directory Structure sample.ear/ sample.ear/meta-inf/ sample.ear/meta-inf/application.xml sample.ear/meta-inf/trifork-app-conf.xml sample.ear/sample.jar/ sample.ear/sample.jar/meta-inf/ sample.ear/sample.jar/meta-inf/ejb-jar.xml sample.ear/sample.war/ sample.ear/sample.war/web-inf/ sample.ear/sample.war/web-inf/web.xml sample.ear [../../../samples/stateless/src/sample.ear] contains two deployment descriptors: application.xml [../../../samples/stateless/src/sample.ear/meta-inf/application.xml] and trifork-app-conf.xml [../../../samples/stateless/src/sample.ear/meta-inf/trifork-app-conf.xml], sample.jar [../../../samples/stateless/src/sample.ear/sample.jar] contains one deployment descriptor: ejb-jar.xml [../../../samples/stateless/src/sample.ear/sample.jar/meta-inf/ejb-jar.xml], and sample.war [../../../samples/stateless/src/sample.ear/sample.war] contains one deployment descriptor: web.xml [../../../samples/stateless/src/sample.ear/sample.war/web-inf/web.xml]. The trifork-app-conf.xml [../../../samples/stateless/src/sample.ear/meta-inf/trifork-app-conf.xml] is the only deployment descriptor specific for the Trifork Enterprise Application Server, the remaining are general J2EE deployment descriptors. Successively the deployment descriptors will be described further: The Application Deployment Descriptor The trifork-app-conf Deployment Descriptor The Ejb-jar Deployment Descriptor The Web Deployment Descriptor From the four deployment descriptors, the ejb-jar.xml deployment descriptor is involved with the specification of a session bean. The trifork-app-conf.xml shows the binding of JNDI-names. Specifications of the JSP page and the JavaBean wrapper are not done in any deployment descriptors The Application Deployment Descriptor The application.xml [../../../samples/stateless/src/sample.ear/meta-inf/application.xml] deployment descriptor specifies, which modules are contained in the enterprise archive. Example Application.xml <!DOCTYPE application PUBLIC '-//Sun Microsystems, Inc.//DTD J2EE Application 1.3//EN' ' <application> <display-name>temperature Converter Sample</display-name> <module> <web> <web-uri>sample.war</web-uri> <context-root>example3</context-root> </web> </module> <module> <ejb>sample.jar</ejb> </module> </application> 304

315 Chapter 29. Simple examples In this example, two modules are contained - the web module containing the JSP page and JavaBean wrapper, and the EJB module containing the TempConverter session bean The trifork-app-conf Deployment Descriptor The trifork-app-conf.xml [../../../samples/stateless/src/sample.ear/meta-inf/trifork-app-conf.xml] deployment descriptor is the Trifork Enterprise Application Server deployment descriptor, which is a vendor-specific deployment descriptor. Example trifork-app-conf.xml <!DOCTYPE trifork-app-conf PUBLIC '-//Trifork Technologies//DTD Trifork System Descriptor1.0//EN ' <trifork-app-conf> <web-app> <display-name>temperature Converter Sample</display-name> <context-root>example3</context-root> </web-app> <enterprise-beans> <ejb> <ejb-name>ejb/tempconverter</ejb-name> <jndi-name>ejb/tempconverter</jndi-name> </ejb> </enterprise-beans> </trifork-app-conf> In this example, only the context root and the JNDI-name of the TempConverter session bean are specified. This is done through the <context-root> and the <jndi-name> elements, respectively. The deployment descriptor binds the session bean to a JNDI-name. The TempConverter session bean reffered through <ejb-name> is bound to the JNDI-name ejb/tempconverter. The <ejb-name> refers the specification given in the ejb-jar.xml deployment descriptor The Ejb-jar Deployment Descriptor The ejb-jar.xml [../../../samples/stateless/src/sample.ear/sample.jar/meta-inf/ejb-jar.xml] is the deployment descriptor specifying the enterprise java beans in the archive. Example Ejb-jar.xml <!DOCTYPE ejb-jar PUBLIC '-//Sun Microsystems, Inc.//DTD Enterprise JavaBeans 2.0//EN' ' <ejb-jar> <enterprise-beans> <session> <ejb-name>ejb/tempconverter</ejb-name> <home>com.trifork.ejb.tempconverter.tempconverterhome</home> <remote>com.trifork.ejb.tempconverter.tempconverter</remote> <ejb-class>com.trifork.ejb.tempconverter.tempconverterbean</ejb-class> <session-type>stateless</session-type> <transaction-type>container</transaction-type> </session> </enterprise-beans> </ejb-jar> The <session-type> specifies, which kind of session bean this is. Possible values are {Stateless, Statefull} The Web Deployment Descriptor The web.xml [../../../samples/stateless/src/sample.ear/sample.war/web-inf/web.xml] is the deployment descriptor specifying the web module in the enterprise archive. 305

316 Chapter 29. Simple examples Example Web.xml <!DOCTYPE web-app PUBLIC '-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN' ' <web-app> <display-name>temperature Converter Sample</display-name> </web-app> The web deployment descriptor is practically empty, since the web component consists of a JSP page and a JavaBean wrapper only - and it is not necessary to specify JSP and JavaBean in the web deployment descriptor Building, deploying, and running the example An ANT build script has been provided for the example. This script can be used for building and deploying the example application. You can also deploy the application manually with the trifork command Building the example To build and deploy the archive, access the root of the example [../../../samples/stateless] in a command prompt. Next, edit the trifork.install.dir in the build.xml file property to reflect the server directory of server installation. Finally, build the archive by using the build.xml [../../../samples/stateless/src/build.xml] Ant script: Example Building the application <INSTALLATION_DIRECTORY>/server/ant/bin/ant build This will build the sample.ear [../../../samples/stateless/build/sample.ear] and place it in the build directory. This enterprise archive can then be deployed into the Trifork Enterprise Application Server Deploying the application Deploying the application requires tree steps: Creating a system container. Deploying the archive to the server. Creating a database table for the bean. Example Creating a system <INSTALLATION_DIRECTORY>/server/ant/bin/ant create-systemcontainer or <INSTALLATION_DIRECTORY>/domains/bin/trifork system create sessionexample This will create a system called sessionexample. If a system named sessionexample already exists, performing the create command will not affect the system or any existing applications inside it, but merely result in an error message. Next, deploy the archive to the server: 306

317 Chapter 29. Simple examples Example Deploying the application <INSTALLATION_DIRECTORY>/server/ant/bin/ant deploy or <INSTALLATION_DIRECTORY>/domains/bin/trifork system archive deploy sessionexample <INSTALLATION_D This will deploy the sample.ear to the sessionexample system Running the example If the output of this command is a success, then open a webbrowser and access the example at this URL: This concludes the example. Try performing some experiments by modifying the source code, and repeat the build, deploy, and run procedure described above, and see that your changes are reflected in the running application. 307

318 Chapter 30. Advanced examples This chapter contains an example for the advanced user: Connecting to a Session bean using an J2EE application client - this example furthermore shows how to make a login from an application client It deals with issues more advanced than the examples in Chapter 29. The example is furthermore not documented as thoroughly as the ones on Chapter 29 since the advanced user should be able to understand it by looking at the source code J2EE application client This example shows how to: Write a J2EE application client Do a login from a J2EE application client Deploy a J2EE application client to a Trifork Enterprise Application Server Execute a J2EE application client on a Trifork Enterprise Application Server The source code and build script for the TION_DIRECTORY/samples/appclient directory. example can be found in the INSTALLA The example application This example consists of three J2EE components: Two Session beans One application client The two session beans are fairly simple. The two beans are called SessionBean1 and SessionBean2. The first session bean (called SessionBean1) provides a single method called methodcall, which the client calls. When the method is called, SessionBean1 looks up SessionBean2 and calls the method methodcall on this bean. The methodcall method on SessionBean2 prints out the string "A method call" to standard output whenever it is called. SessionBean1 is deployed with security permissions, so only valid users in the allowedusers security-role are allowed to invoke methods on it. To summarize, the flow of the application is: The application client attempts to make a login If successful it looks up SessionBean1 and calls the methodcall method on it SessionBean1 looks up SessionBean2 and calls the methodcall method on it The methodcall method of SessionBean2 prints out "A method call" to standard output Writing the application client 308

319 Chapter 30. Advanced examples The source code for the application client TION_DIRECTORY/samples/appclient/src/Client.java can be found in INSTALLA- The Client class is fairly simple. The only really interesting code is in the login() method (see Figure 30.1): First an instance of the MyCallBackHandler is created. The MyCallBackHandler class can be found in the same directory as the Client class. The MyCallBackHandler class implements the CallbackHandler interface and is used by the server to ask the client for username and password. It is up to the programmer of the client how the user should specify these. In this example the user is simply prompted on the command line. Next the current subject is retrieved from the context Then a login context is established using the callback handler and the subject The final step is to make the actual login. This is done by calling the login method on the login context When the login is made, a number of different exceptions can be thrown. In the example we simply catch all of them. Figure The login() method from the Client class public boolean login() { try { MyCallBackHandler clientcbhandler = new MyCallBackHandler(); Subject subject = Subject.getSubject(AccessController.getContext()); LoginContext logincontext; if( subject == null ) { logincontext = new LoginContext("EASCLIENT", clientcbhandler); } else { logincontext = new LoginContext("EASCLIENT", subject,clientcbhandler); } logincontext.login(); return true; } catch (Exception e) { System.out.println("Exception: " + e); } return false; } Building and deploying the application To build the application simply go to the INSTALLATION_DIRECTORY/samples/appclient. Next, edit the trifork.install.dir property in the build.xml file to reflect the server directory of your server installation. Finally, build the archive using the build.xml Ant script: <INSTALLATION_DIRECTORY>/server/ant/bin/ant Before you can deploy the application, you need to create a system container and the user you will use to login in with though the application client. To do this, issue the following command: <INSTALLATION_DIRECTORY>/server/ant/bin/ant deploy.prepare This will create a system container named appclient, and a J2EE user with the following data: username: j2ee, password: j2ee Now, deploy the application by issuing the following command: 309

320 Chapter 30. Advanced examples <INSTALLATION_DIRECTORY>/server/ant/bin/ant deploy This will deploy the session beans to the server, and leave an application client called client.tda for you to run Running the application client Application clients must be run in the client container. To do this issue the following command: <INSTALLATION_DIRECTORY>/domains/default/bin/trifork client run <INSTALLATION_DIRECTORY>/samples/ When the client is running you will be prompted for a username and password to connect with. Use j2ee for both of these. 310

321 Chapter 31. Application examples This chapter contains an application example: The Petstore blueprint example Java Pet Store Demo The Java Pet Store Demo is a sample application brought to you by the Java BluePrints [ program at Java Software [ Sun Microsystems [ This sample application demonstrates how to use the capabilities of the J2EE platform to develop robust, scalable, portable, and maintainable e-business applications. It comes with full source code and documentation, so you can experiment with the J2EE technologies and learn how to use them effectively to build your own enterprise solutions. You can download the demo, including source and documentation here [ Using the Demo This section describes how to use the Java Pet Store Demo. To build the application simply go to the INSTALLATION_DIRECTORY/samples/petstore. Next, edit the trifork.domain.dir property in the build.xml file to reflect your domain directory. The build.xml script expects a clean installation. Now deploy the application by issuing the following command: <INSTALLATION_DIRECTORY>/server/ant/bin/ant Note, that if the appclient example has been run, the j2ee user must be removed by issuing the following command: <INSTALLATION_DIRECTORY>/domains/default/bin/trifork realm removeuser j2ee 311

322 Chapter 31. Application examples Visiting the Storefront Using a browser, go to the following URL: and click "enter the store" Creating a New User If this is your first time visiting the store, create a new user before making a purchase. 1. Click Sign In on the home page. 2. Fill out the form titled, "I would like to sign up for an account", and click Create New Account. 3. Enter your account info, and click Submit Placing an Order To purchase a bulldog, for example, follow these steps: 312