514 WebSphere Studio Application Developer Version 5 Programming Guide Server tools feature Application Developer provides the server tools feature to support you in testing your applications. It provides test environments where you can test Web modules with servlets, JSPs, and HTML files. It also provides a tool called the universal test client (UTC) with which you can test your EJB modules and Web services (see “Universal test client” on page 428). The server tools feature uses servers and server configurations to test and deploy your projects. Servers identify server instances where you can run your projects and server configurations contain setup information for the servers. You can have multiple server configurations with different settings and then select which configuration a particular server should use. This allows you to easily switch between different setups of memory configurations, data sources, trace settings, class loading policies, and so forth. Servers and server configurations are kept in server projects. If you do not have any servers or server configurations set up, you can have the server tools create them for you automatically. However, doing it manually using the server tools wizards gives you more control over what is being set up. The server tools feature allows you to create servers and server configurations that can run resources from the following types of projects: Web projects—containing servlets, JSPs, HTML files, and Java beans. Web projects can also contain Web services to be tested. EJB projects—containing EJB beans. Enterprise application projects—containing Java Archive (JAR) files, Web and EJB projects. Using the Server perspective, you can manage the servers and server configurations and start, stop, or restart them. When running the Application Developer built-in test environments, the server is running against the resources in your workspace. This allows you to add, change, or remove resources from your enterprise application, and the server is able to pick up these changes without having to be restarted. Supported run-time environments The server tools feature allows you to test your applications in different run-time environments that can be installed as part of Application Developer (built-in), and run locally on the same machine or remotely on another machine. Table 15-1 describes the different options available with Application Developer 5.0. Chapter 15. Servers and server configurations 515 Table 15-1 Supported test server environments WebSphere Application Server 5.0, WebSphere Application Server 5.0 Express, and WebSphere Application Server 4.0 Advanced Edition Single Server ship with Application Developer 5.0 and can be selected during installation. The local and remote WebSphere Application Server environments, as well as the Apache Tomcat servers, must be installed separately. When using either a local or remote WebSphere Application Server environment, a tool called the IBM Agent Controller is used to control the server (start, stop, restart, and profiling). It must therefore be installed on the same machine as the WebSphere Application Server environment to use. The IBM Agent Controller is not required when using the Application Developer built-in test environments or when using Apache Tomcat, unless you want to perform profiling (see Chapter 20, “Profiling applications” on page 655). Each environment provides different capabilities as shown in Table 15-2. Table 15-2 What projects can run in which environment Environment Built-in Local Remote WebSphere Application Server 5.0 Yes Yes Yes WebSphere Application Server 5.0 Express Yes Yes Yes WebSphere Application Server 4.0 Advanced Edition Single Server Ye s Yes Yes WebSphere Application Server 4.0 Advanced Edition No Yes Yes Apache Tomcat 3.2, 4.0, and 4.1 Yes Yes No Environment Enterprise Application Projects EJB projects Web projects WebSphere Application Server 5.0 Yes Yes Yes WebSphere Application Server 5.0 Express No No Yes WebSphere Application Server 4.0 Advanced Edition Single Server Ye s Yes Yes WebSphere Application Server 4.0 Advanced Edition Ye s Yes Yes Apache Tomcat 3.2, 4.0 and 4.1 No No Yes 516 WebSphere Studio Application Developer Version 5 Programming Guide A run-time environment called the TCP/IP Monitoring Server is also packaged with the server tools feature. This is a simple server that monitors all the requests and responses between the Web browser and an application server. It also monitors TCP/IP activity. This run-time environment can only be run locally. You cannot publish projects to the TCP/IP Monitoring Server. There is also a new server type called the J2EE Publishing Server. This feature allows you to deploy J2EE applications developed in Application Developer to remote J2EE compliant servers that require minimal configuration (for example, Tomcat/JBoss), and then test the client applications from the Application Developer Workbench. We do not cover this server type in this book, but if you are interested in learning more about it, you can take a look at the following WebSphere Developer Technical Journal tutorial: http://www7b.software.ibm.com/wsdd/techjournal/0302_koo/koo.html Creating server and server configuration automatically If there are no servers or server configurations defined, you can have Application Developer create them for you automatically. All you need to do is to select Run on Server from the context menu of the project you want to run (Figure 15-1) and then select the type of server to create (Figure 15-2). The server options available to you in Figure 15-2 depend on what servers you installed with Application Developer. If you also select the Set server as default (do not prompt) you will not be prompted for which server to run this project on when using the Run on Server option in the future. This setting is available in the project’s properties if you want to change it later. Notes: WebSphere Application Server 4.0 supports J2EE 1.2 projects only. To run a J2EE 1.3 project, you must use a WebSphere Application Server 5.0 server. Note: Before you run the application for the first time, make sure that no servers or server configurations exist, otherwise you will not see the same dialogs as shown here. Chapter 15. Servers and server configurations 517 Figure 15-1 Select Run on Server from the context menu Figure 15-2 Selecting a server type The server tools feature automatically does the following for you: Opens the Server perspective Creates a server project called Servers Creates the server you selected and gives it a default name (for example, WebSphere v5.0 Test Environment) 518 WebSphere Studio Application Developer Version 5 Programming Guide Creates a corresponding server configuration and gives it a default name (for example, WebSphere v5.0 Server Configuration) Sets the server to use the server configuration Adds your project to the server configuration, and, if selected, sets the server as the default for your project Publishes your project to the server Starts the server Opens the Debug view and the Source pane, if there are breakpoints set in the file Displays the file in the Web browser as shown in Figure 15-3. Figure 15-3 Application running in built-in test environment Note: If you select Run on Server from the context menu of an Enterprise Application project, Application Developer will not open a Web browser for you. If you select a Web project, however, it will open the Web browser and go to the URL of the Web project’s context root. If you select an EJB project, the universal test client is started. Chapter 15. Servers and server configurations 519 Creating server and server configuration manually When creating servers and server configurations manually, you can reuse an existing server project or create a new project. This section walks you through the process of creating a new server project and adding a remote WebSphere Application Server 5.0 server and server configuration. It then runs the ItsoProGuide project in this remote environment. Before proceeding, you should make sure that the following products are installed on the remote machine: WebSphere Application Server 5.0 IBM Agent Controller Also make sure that only the IBM Agent Controller is started (this will control the starting and stopping of the remote WebSphere Application Server). Creating a Server project Skip this step if you created the Server project in “Creating a server for testing” on page 224. From the File menu, select New -> Project and then Server -> Server Project . The Create a New Server Project wizard opens (see Figure 15-4). Enter ItsoProGuideServer as the project name and then click Finish . Figure 15-4 Create server project wizard Using a built-in server: See “Creating a server for testing” on page 224 for instructions to define a built-in server and server configuration (ItsoServer). 520 WebSphere Studio Application Developer Version 5 Programming Guide Creating a remote server and file transfer mechanism Once a server project is available, you can create a server to identify the run-time environment you want to use for testing your project. If you create a server that is not built into Application Developer (that is, local or remote) you also have to define how the application and server configuration should be transferred to the server when published. There are two methods available, copy and FTP. Copy performs a simple file copying, and FTP uses the FTP protocol. For a local server, the copy mechanism is the best choice. If you are creating a server on a remote machine and want to use the copy mechanism you must have the drive where the server (only WebSphere Application Server is supported for remote testing) is installed on the remote machine mapped to a local drive letter on the Application Developer machine. To use the FTP mechanism, you must have an FTP server active on the remote machine. We will not explain how to set this up, as that depends on the FTP server chosen. We will, however, explain how to set up Application Developer to use both copy and FTP file transfers. Creating the server In this example we will create a server pointing to a remote WebSphere Application Server 5.0 environment installed on a machine called vertex. If you would like to create a server pointing to a local server environment (on your own machine) you should still select Remote server but then use IP address 127.0.0.1 or hostname localhost. In the Server perspective, Navigator view select the ItsoProGuideServer project and select New -> Server from its context menu. The Create New Server wizard opens as shown in Figure 15-5. This wizard creates a new server with the information required to publish and run projects on built-in, local, or remote run-time environments. In the Server name field, enter a name for the server. As the method of file transfer is associated with the server, it is a good idea to give the server a name identifying the method used. We will configure this remote server to use the copy method, so we call the server WebSphere v5.0 on vertex (Copy). Make sure that the project ItsoProGuideServer is selected, and select WebSphere Version 5.0 Remote Server as the server type. Then click Next . Chapter 15. Servers and server configurations 521 Figure 15-5 Create new server wizard On the WebSphere Remote Server Settings page (see Figure 15-6) enter the IP address or hostname of the remote machine running the WebSphere Application Server 5.0 product. Then click Next . Figure 15-6 Specifying remote server address 522 WebSphere Studio Application Developer Version 5 Programming Guide Once Application Developer has connected to the remote IBM Agent Controller, the window shown in Figure 15-7 is displayed. Note: At this point, Application Developer attempts to contact the IBM Agent Controller running on the remote machine to retrieve configuration information about the remote environment. If this procedure fails, the following tips may be helpful in resolving the problem (the actions should be performed on the remote machine where the IBM Agent Controller is running): Verify that the IBM Agent Controller process is running either by opening a command prompt and typing net start or selecting the My Computer icon and then selecting Manage -> Services and Applications -> Services from its context menu. You should see a process called IBM Agent Controller running. Verify that you can ping the remote machine and that there is no firewall blocking the communication (the IBM Agent Controller listens on port 10002). Verify that the configuration file for the IBM Agent Controller contains correct values for the WAS_HOME (in case of WebSphere Application Server 4.0) and WAS_HOME_V5 (in case of WebSphere Application Server 5.0) variables. The configuration file is called: C:\Program Files\IBM\IBM Agent Controller\config\serviceconfig.xml Open the file, find the AgentControllerEnvironment section, and look for the following line (example for WebSphere Application Server 5.0): <Variable name="WAS_HOME_V5" value="C:\WebSphere\AppServer" position="replace"/> Make sure the value specifies the full path of your WebSphere Application Server 5.0 installation directory (it must not just say %WAS_HOME_V5%). Then save the file and restart the IBM Agent Controller. Examine the log file to see if it has any error messages explaining the error condition: C:\Program Files\IBM\IBM Agent Controller\config\servicelog.log Chapter 15. Servers and server configurations 523 Figure 15-7 Specifying remote server settings The WebSphere installation directory is prefilled with the information the IBM Agent Controller collected on the remote machine. If you select the Use default WebSphere deployment directory it means that Application Developer will publish the enterprise application and server configuration to the directory where the remote WebSphere Application Server installation keeps its information, overwriting the information there. Deselecting this check box allows you to enter another directory (that should exist on the remote machine) where the information should be published instead. When publishing to the remote server, the Enterprise Application and server configuration will be published to the installedApps, config, and properties directories under the remote deployment directory. If you want to run DB2-based applications, you must define the DB2 driver location. If you forget to specify the driver location, you can open the configuration editor later and specify the location on the Server page (see Figure 15-30 on page 544). c:\SQLLIB\java\db2java.zip . the WebSphere Application Server 5. 0 product. Then click Next . Figure 15- 6 Specifying remote server address 52 2 WebSphere Studio Application Developer Version 5 Programming Guide Once Application. 51 4 WebSphere Studio Application Developer Version 5 Programming Guide Server tools feature Application Developer provides the server tools feature to support you in testing your applications selected and gives it a default name (for example, WebSphere v5.0 Test Environment) 51 8 WebSphere Studio Application Developer Version 5 Programming Guide Creates a corresponding server configuration