Adding a Host

Before you can deploy applications, you need to tell JavaMonitor which hosts you want to use for deployment. (See Load Balancing for additional information regarding load balancing and hosts added in JavaMonitor.) Figure 5-1 shows JavaMonitor’s Hosts page, which you use to add and configure hosts.

Follow these steps to add an application host to a deployment:

1. In JavaMonitor, click the Hosts tab.

2. Enter the name or IP address of the host you want to add in the host text input field.

   The computer must be running a wotaskd process in the port that JavaMonitor sends its lifebeats to.

   Avoid using a loopback address (a connection that does not go over the network), such as localhost or 127.0.0.1. If you do, it must be the only application host in your site.

3. Choose the appropriate platform from the pop-up menu.

4. Click Add Host.

Figure 5-2 shows the Hosts page after a host has been added.

Configuring a Host

To change the configuration of an application host, click the Config button on the Hosts page. A page similar to the one in Figure 5-3 appears. It allows you to set the type of the host and to resynchronize configuration information if needed.

Viewing a Host’s Configuration

To display the configuration of a host, click YES, on the Hosts page. A page similar to the one in Figure 5-4 is displayed in a separate web browser window.

This page displays the current state of the host in several sections.

The section visible in Figure 5-4 shows the contents of the host’s SiteConfig.xml file. For more information on the SiteConfig.xml file, see Configuration Files.

The next section shows the adaptor configuration sent to local HTTP adaptors, which lists all running application instances that wotaskd knows about (this includes JavaMonitor processes).

<?xml version="1.0" encoding="ASCII"?>

<adaptor>

    <application name="JavaMonitor">

        <instance id="-8888" port="8888" host="ebruce2.apple.com"/>

    </application>

</adaptor>

Note that the instance ID of the JavaMonitor process is negative. When wotaskd receives a lifebeat from an unregistered application instance (one that has not been added to your site through JavaMonitor), it discloses the instance to the web server with a negative ID number. This allows developers (internal users) to connect to development instances through the HTTP adaptor for testing purposes. To address security concerns, external users can connect to instances with negative ID numbers only if they know the instance’s port number. However, this can be disabled by setting WODirectConnectEnabled to false. See WODirectConnectEnabled in WebObjects Application Properties Reference for details.

To connect to a development instance through the web server, the instance must run on the same computer that the web server runs on, and the computer must be the localhost.

Next is the local adaptor configuration sent to remote HTTP adaptors. This section lists all instances that are active, registered (configured through JavaMonitor), and available to external users.

<?xml version="1.0" encoding="ASCII"?>

<adaptor>

  <application name="Payroll" urlVersion="4">

    <instance id="1" port="2001" host="ebruce.apple.com"/>

  </application>

  <application name="HR" urlVersion="4">

    <instance id="1" port="2002" host="ebruce.apple.com"/>

  </application>

</adaptor>

The next section shows the contents of the HTTP adaptor configuration file. If you tell wotaskd to write the HTTP adaptor configuration file, it lists all the registered application instances on the site, whether they are running or not. (This file is identical across all the site’s application hosts.) See The HTTP Adaptor Configuration File for more information and an example of the file’s contents.

The last section lists information on the wotaskd process’s environment, including its port and multicast address.

The Configuration Directory is: /Library/WebObjects/Configuration/

Wotaskd is NOT writing WOConfig.xml to disk

The multicast address is: 239.128.14.2

This wotaskd is running on Port: 1085

Wotaskd is NOT responding to Multicast

WOAssumeApplicationIsDeadMultiplier is 4

The System Properties are: ...

Building for Deployment with Xcode

To perform a split installation of your application using Xcode 2.1 or later, navigate to your project’s directory and execute the following commands as the root user using your shell editor:

xcodebuild install -configuration Deployment DSTROOT=/

xcodebuild install -configuration WebServer DSTROOT=/

To perform a split installation of your application using Xcode 2.0 or earlier, navigate to your project’s directory and execute the following commands as the root user using your shell editor:

xcodebuild install -buildstyle Deployment DSTROOT=/

xcodebuild install -buildstyle WebServer DSTROOT=/

Building for Deployment with Ant

Starting with WebObjects 5.4 and later, Xcode no longer supports building for deployment for new WebObjects applications based on the Ant build system. As an alternative, you can use the Java Ant build tool to do a split installation.

The steps to build for deployment described below apply to a WebObjects example project. You can find the WebObjects examples in the /Developer/Examples/JavaWebObjects directory.

To perform a split installation of your application using the WebObjects Ant build system, navigate to your project’s directory and execute the following commands while logged in as the root user from a shell:

ant deployment

This command places the application files in the /Library/WebObjects/Applications directory and the web server resources in the Document Root/WebObjects directory.

The WebObjects Ant build system provides three types of application bundles in the dist directory of your project folder:

• The legacy WOA application bundle

  This is the traditional WebObjects WOA or Framework bundle.

• The self-contained WOA application bundle

  This self-contained WOA bundle embeds all dependent framework Jar files and resources within the bundle. The class path is configured to look for the internal bundled classes instead of the installed ones. It is generally recommended that you use a self-contained WOA bundle for deployment to keep the WebObjects application running even when the WebObjects runtime on the deployment machine is upgraded to a different version.

• A J2EE-style war bundle with an embedded WebObjects application

After producing a split installation on the development computer, copy the WOA bundle and the application’s resources to their final destination (or destinations, in case you want to run instances of the application in several computers) and use JavaMonitor to configure the deployment.

You can place application files in any directory of the application host. Web server resources, however, must be placed in the Document Root directory of the application host. Make sure that you use the following organization:

<Web server Document Root>/

    WebObjects/

        AppName.woa/

            Contents/

                WebServerResources/

                    <resource files>

In most situations you should deploy an application’s logic and resources on different computers. For example, while developing an application on Mac OS X, you can test it with the web server included with the system. However, you should not deploy the application in Mac OS X. Always deploy WebObjects applications on Mac OS X Server.

Adding an Application

You add applications to your site using JavaMonitor’s Applications page, shown in Figure 5-5.

Follow these steps to add an application to your site:

1. Enter the application’s name (without the extension) in the Add Application Named text field.

2. Click Add Application.

Configuring an Application

After you add an application, the application configuration page is displayed. This page has five major sections, which you can show and hide using the disclosure triangles:

• The New Instance Defaults section lets you set the default values for the instance settings for application instances you add afterward. For example, you can change the default JVM setting for your application. See New Instance Defaults for details.

• The Application Settings section contains properties that apply to all the instances of the application. For more, see Application Settings.

• The Scheduling section allows you to individually schedule instances to restart at specific intervals. See Scheduling for details.

• The Email Notifications section is where you specify the list of email addresses you want email notifications to be sent to. For details, see Email Notifications.

• The Load Balancing and Adaptor Settings section lets you choose the algorithm that the HTTP adaptor uses to perform load balancing among the instances of the application. See Load Balancing and Adaptor Settings.

New Instance Defaults

Figure 5-6 shows the section of the application configuration page that allows you to set defaults for the application instances. If application instances are running when you change these settings, you need to restart them to apply your changes. For details on the options shown on this page, see the description below or refer to WebObjects Application Properties Reference as indicated.

• Path: The file system path of the application launch script in the ".woa" directory.

• Auto Recover: Indicates whether JavaMonitor automatically restarts instances that are manually shut down or that have become unresponsive.

• Minimum Active Sessions: The minimum number of active sessions an instance must have before JavaMonitor can terminate it.

• Caching Enabled: See the description of WOCachingEnabled in WebObjects Application Properties Reference.

• Debugging Enabled: See the description of WODebuggingEnabled in WebObjects Application Properties Reference.

• Output Path: See the description of WOOutputPath in WebObjects Application Properties Reference.

• Auto-Open in Browser: See the description for WOAutoOpenInBrowser in WebObjects Application Properties Reference

• Lifebeat Interval: See the description of WOLifebeatInterval in WebObjects Application Properties Reference.

Here’s an explanation of the buttons on the page:

• Push: updates the value of the property for new and configured (registered) instances of the application. The changes take effect after the instances are restarted.

• Push All: updates the value of the all the properties for new and configured instances of the application. As with Push, the changes become effective when the instances are restarted.

• Update for New Instances Only: sets the defaults to be used when you create new instances of the application. The properties of existing instances are not changed.

• Path Wizard: opens a tool that allows you to navigate through a host’s file system.

Application Settings

Figure 5-7 shows the Application Settings section of the application configuration page. In it, you define application settings that apply to all the instances of the application. For details of the properties shown in this section, see the description below or refer to WebObjects Application Properties Reference as indicated.

• Name: This property is used by the HTTP adaptor to implement load balancing. The adaptor can load-balance only between instances with the same application name. The property can be used to create groups of instances, even when the instances share the same executable file. See the description of the WOApplicationName application property in WebObjects Application Properties Reference.

• Starting Port: The first port number JavaMonitor tries to assign to a new instance of the application. If the port is in use by another instance of any application, JavaMonitor uses the next unassigned port number.

• Time Allowed for Startup: The number of seconds JavaMonitor waits for an instance to start before determining that the instance failed to start.

• Phased Startup: If this option is selected, when a wotaskd process starts up, the instances that it manages that have Auto Recover selected are started one at a time instead of all at once. This option is selected by default. For more information, see the description of Auto Recover in New Instance Defaults.

• Adaptor: The default adaptor class an instance uses (This is not the HTTP adaptor used by the web server.) You use this if the application defines a subclass of the WOAdaptor class to be used to create adaptor objects (instead of using the WOAdaptor class itself).

• Minimum Adaptor Threads: The initial number of worker threads the adaptor creates to handle requests to the application. It applies only to adaptor processes of the WODefaultAdaptor class in WebObjects 5.

• Maximum Adaptor Threads: The maximum number of worker threads the HTTP adaptor creates to handle requests to the application. It applies only to adaptor processes of the WODefaultAdaptor class in WebObjects 5. The purpose of these threads is to process TCP or UDP packets; they have nothing to do with request processing.

• Adaptor Threads: The number of worker threads that the HTTP adaptor creates to handle requests to the application. It applies only to adaptor objects of the WODefaultAdaptor class in WebObjects 4.5.

• Listen Queue Size: Determines the depth of the listen queue. While the instance handles a request, the socket buffer can hold as many additional requests as this setting indicates before it starts refusing them. Keep in mind that if an application instance’s listen queue size becomes full and a request is refused by it, the request does not get redirected to another instance with space left over in its queue. The client has to resend the request. If you expect spikes in the traffic level of a specific application, consider increasing the listen queue size. Doing so does not necessarily improve performance or allow the instance to process more requests at sustained high loads, but it may reduce the number of times an application’s user must resend a particular request during high-traffic periods.

• Project Search Path: List of file-system paths that WebObjects searches in rapid-turnaround mode. These are the paths where your projects are located (relative paths are relative to your project’s launch script). WebObjects searches for your projects in the order in which you specify the paths. You must specify the paths using the following format: ("firstPath","secondPath",...)

• Session TimeOut: Specifies the time interval, in seconds, since the last request is processed after which the session times out and is terminated.

• Statistics Page Password: Specifies the password that must be entered to gain access to the instance statistics page of an application instance.

Scheduling

Figure 5-8 shows the Scheduling section of the application configuration page. After you add instances of an application, you can schedule them individually here. For details, see the description below or WebObjects Application Properties Reference.

• Graceful Scheduling: Determines whether an instance is shut down gracefully or immediately at its scheduled shut-down time. During a graceful shutdown, the instance does not create sessions for new users (they are automatically directed to other available instances, if any). Existing sessions remain active until they time out or are destroyed programmatically. When the number of active sessions drops to the value set for the Minimum Active Sessions property, the instance is restarted. When Graceful Scheduling is not selected for the instance, it is restarted immediately, terminating active sessions. See description of Minimum Active Sessions in New Instance Defaults for more information.

• Is Scheduled: Determines whether the schedule defined for a particular instance is active.

• Types of Schedule:

  There are three types of schedule available for instances:

  • Hourly: The instance is restarted after a certain number of hours from a particular hour.

  • Daily: The instance is restarted at a particular hour every day.

  • Weekly: The instance is restarted a particular hour on a specific day of the week.

Email Notifications

Figure 5-9 shows the Email Notification Settings section of the application configuration page. In it you can enter the email addresses of people that are to be notified when instances of the application terminate unexpectedly. For more information, see WebObjects Application Properties Reference.

Load Balancing and Adaptor Settings

Figure 5-10 shows the Load Balancing and Adaptor Settings section of the application configuration page. This is where you enter values for the HTTP adaptor’s configuration properties, including the load-balancing algorithm the adaptor uses to balance user load among the application instances. These settings override the values entered in the HTTP Adaptor Settings section of the Site page. For information on the properties you can set, see the description below or WebObjects Application Properties Reference as indicated.

• Load-Balancing Scheme: The load-balancing method used by the adaptor for instances of the application. The options available are Round Robin, Random, and Load Average. You can also use a custom load balancer by choosing Custom in the pop-up menu and entering the load balancer’s name in the Custom Scheduler Name text field.

• Retries: The number of times a request is retried (trying several instances) if a communications failure occurs before an error page is returned to the web server.

• Redirection URL: The URL to which the user is redirected when an instance fails to respond to a direct request.

• Dormant: The number of times the adaptor skips an instance of the application before trying again.

• Send Timeout: The maximum number of seconds before the adaptor gives up attempting to send data to an instance of the application.

• Receive Timeout: The length of time, in seconds, the adaptor waits for a response from an instance of the application before giving up.

• Connect Timeout: The maximum number of seconds before the adaptor gives up connecting to an instance.

• Send Buffer Size: The size, in bytes, of the TCP socket send buffer used for adaptor-to-instance communication.

• Receive Buffer Size: The size, in bytes, of the TCP socket receive buffer used for HTTP adaptor-to-instance communication.

• Connection Pool Size: The maximum number of simultaneous connections the HTTP adaptor should keep open for each configured instance.

• URL Version: The WebObjects version to use for URL parsing and formatting. All WebObjects 4, 4.5, and 5 applications use version 4 URLs by default.

Adding Application Instances

After configuring an application in JavaMonitor, you can create application instances with ease.

1. In JavaMonitor, click the Applications tab. The Applications page is displayed, as shown in Figure 5-11.

   

2. Click the Detail View button under View Instances. The application detail page is displayed, as shown in Figure 5-12.

   

3. Enter the number of instances you want to add in the text input field.

4. Choose the application host you want the instances to run on from the pop-up menu.

   The application must be installed on the host you choose; otherwise, an error message is displayed when you try to start the instance. See Installing Applications for details.

5. Click Add. Your web browser displays a page like the one in Figure 5-13.

   

The Status column indicates whether the instance is on or off. The first time the page is displayed, the newly added instances are off. After a moment (or if you click Refresh Now), and if Auto Recover is enabled for the instance, the page refreshes, showing that the instance is active. For details on Auto Recover, see the description of Auto Recover in New Instance Defaults. (Read Setting JavaMonitor Preferences for how to change the length of the interval between the automatic updates of the application detail page.)

Figure 5-14 shows the application detail page of the HR application, with two instances configured.

The following list describes the instance configuration information that appears in the application detail page:

• Page heading: A link to the application through the HTTP adaptor. When you click it, the adaptor uses load balancing to determine which of the application’s instances should receive the request. Then, your web browser displays a new window showing your application’s entry page. For this to work, the HTTP adaptor URL has to be set (Configuring Sites shows you how to do this).

• Name: A link to the instance through the HTTP adaptor. When you click it, the request goes through the adaptor but it’s not load balanced. The URL is derived in the same way the URL of the page heading is derived but with the addition of the instance number. Such a URL looks similar to the following:

  http://ebruce2.apple.com/cgi-bin/WebObjects/HR.woa/1

• Host-Port: A direct link to the instance; does not go through the HTTP adaptor.

• Status: Tells whether the instance is on, off, starting, or stopping.

• Start-Stop: Click the green button to turn the instance on or the red button to turn it off.

• Auto Recover: Click to toggle between ON and OFF. This is available only if the instance is not scheduled. See description of Auto Recover in New Instance Defaults.

• Refuse New Sessions: Click to toggle between ON and OFF. When ON, the instance does not accept new users. This is available only if the instance is not scheduled.

• Scheduled: Click to toggle between ON and OFF. When ON, JavaMonitor uses the schedule defined for the instance.

• Configure: Click the Config button to go to the instance configuration page for the instance.

• Delete: Click the Delete button to delete the instance. JavaMonitor displays a confirmation page before executing the deletion.

For an explanation of the columns under Statistics, see The Application Detail Page.

The row with the caption ALL INSTANCES contains buttons that perform some of the functions listed above on all the instances of the application. Clicking Config displays the application configuration page.

Configuring Instances

After adding an instance, you can change its configuration in the instance configuration page, shown in Figure 5-15. You can access this page through the instance’s Config button in the application detail page. It contains two sections: Instance Settings and Adaptor Settings. For information on those sections, see Instance Settings and Adaptor Settings.

Setting a Password for the Instance Statistics Page

For each instance of your application, there’s a statistics page that displays information such as its running time and memory usage. See The Instance Statistics Page for more information on this page. If you want to prevent outside agents from gaining access to the instance statistics page, you can set a password in the Instance Settings section of the instance configuration page. Add the following to the Additional Arguments property:

-WOStatisticsPassword password

Figure 5-16 shows an example where the WOStatisticsPassword argument has been added to the Additional Arguments field.

JavaMonitor Password

You can restrict access to JavaMonitor by requiring its users to enter a password before they can use it. When a site is protected this way, the site’s wotaskd processes are also protected; that is, you cannot directly obtain a wotaskd process’s information by connecting to its port.

Figure 5-19 shows the login page that JavaMonitor displays after you password-protect your site.

When you try to view the configuration of an application host on a site that you’ve password-protected by connecting to the appropriate wotaskd process’s port, you see a page similar to the one shown in Figure 5-20 (the page’s content varies according to your deployment platform).

On password-protected sites, you have to use JavaMonitor to view an application host’s configuration.

Detail-View Refresh Settings

This section allows you to tell JavaMonitor if you want it to refresh the application detail page and how often to do it.