Chapter 1 Configuring Waveset

This chapter describes how to set Waveset properties and configure Waveset servers to run specific tasks.

The information in this chapter is organized into the following topics:

• Using Waveset.properties to Configure Waveset

• Using the Administrator Interface to Configure Waveset

• Reconciler Settings

• Scheduler Settings

• Email Template Server Settings

• Configuring JMX Monitoring

• Editing Default Server Settings

Using Waveset.properties to Configure Waveset

Some Waveset settings can only be updated by editing Waveset.properties in a text editor. The Waveset.properties file is located in the config directory in your base Waveset installation directory ($WSHOME/config or %WSHOME%/config).

The Waveset.properties file is loosely organized into the following sections:

• Misc Options

• Authentication Options

• Object Cache Options

• Provisioning Options

• Task Scheduler Options

• Resource Adapter Options

• List Cache Properties

• Rule Driven Members Cache Properties

• Session Settings

• Server Listeners

• UI Options

• Global Options for the JNDI Context Pooling

• Task Executor Options

• XML Parsing Options

To Edit Waveset.properties

1. Open the Waveset.properties file in a text editor.

   You can find the Waveset.properties file in the config directory in your base Waveset installation directory ($WSHOME/config or %WSHOME%/config).

2. Modify the setting (or settings) that you want to change and save the file.

3. Repeat as needed on other Waveset instances.

Using the Administrator Interface to Configure Waveset

This section provides basic instructions for using the Administrator tool to configure server-specific settings for reconciler, scheduler, JMX and other tasks.

To Configure Waveset Settings from the Administrator Interface

To edit server-specific settings that enable Waveset servers to run only specific tasks

1. In the Administrator interface, click Configure -> Servers.

2. When the Configure Servers page displays, click a server name in the list.

3. When the Edit Server Settings page displays, modify the settings that you want to change, and then click Save.

Reconciler Settings

The reconciler is the Waveset component that performs reconciliation. To learn about reconciliation, see Account Reconciliation in Oracle Waveset 8.1.1 Business Administrator’s Guide.

This section contains instructions to help you perform the following tasks:

• To Configure Reconciler Settings

• To View Reconciler Status

For information about tuning and troubleshooting the reconciler, see Chapter 5, Tracing and Troubleshooting.

To Configure Reconciler Settings

Use the following steps to configure the Reconciler:

1. In the Administrator interface, click Configure -> Servers.

2. When the Configure Servers page displays, click a server name in the list.

3. Select the Reconciler tab.

   Reconciler settings display on the Edit Server Settings page by default.

4. Accept the default values or deselect the Use the default option to specify custom values.

   ---

   Note –

   To change the default reconciler settings used by Waveset servers, see Editing Default Server Settings.

   ---

5. Configure the following settings.

   • Parallel Resource Limit. Specify the maximum number of resource threads that the reconciler can process in parallel. Resource threads allocate work items to worker threads, so if you add additional resource threads, you may also need to increase the maximum number of worker threads. For new installations, the default value is 3.

   • Minimum Worker Threads. Specify the number of processing threads that the reconciler will always keep alive. For new installations, the default value is 2.

   • Maximum Worker Threads. Specify the maximum number of processing threads that the reconciler can use. The reconciler will only start as many threads as the workload requires. This places a limit on that number. Worker threads automatically close if they are idle for a short duration. For new installations, the default value is 6.

To View Reconciler Status

Use the following steps to view reconciler status information:

1. Open the Reconciler Status debug page by typing the following URL into your browser:

   http://<AppServerHost>:<Port>/idm/debug/Show_Reconciler.jsp

   Where AppServerHost is a host that has the reconciler enabled.

   ---

   Note –

   You must have the Debug capability to view /idm/debug/ pages. For information about capabilities, see Assigning Capabilities to Users in Oracle Waveset 8.1.1 Business Administrator’s Guide.

   ---

2. Refresh the Reconciler Status page to view updated reconciler status information. For additional information about this page, click Help.

Scheduler Settings

The Scheduler component controls task scheduling in Waveset.

To configure scheduler settings on a particular server,

1. Follow the first two steps under Using the Administrator Interface to Configure Waveset.

2. Select the Scheduler tab.

   The following Use default options are enabled by default, which allows the scheduler to behave more efficiently when the Waveset server and repository are very busy. You can accept the default settings or deselect the Use default option to specify custom values.

   • Use default (Automatic). Sets the scheduler start up mode to Automatic.

   • Use default (false). Disables scheduler debug tracing.

   • Use default (100). Allows the scheduler to run a maximum of 100 tasks at any one time.

   • Use default (Allow any task). Allows any task to execute on the server.

   To specify custom settings for the scheduler, deselect one or more of the Use default options and configure the following options:

   • Scheduler Startup. Select a startup mode for the scheduler on this server:

     • Automatic. Starts when the server is started. This setting is the default startup mode.

     • Manual. Starts when the server is started, but remains suspended until manually started.

     • Disabled. Does not start when the server is started.

   • Tracing Enabled. Select this option to activate scheduler debug tracing to standard output on this server.

   • Maximum Concurrent Tasks. Select this option to specify the maximum number of tasks, other than the default, that the Scheduler will run at any one time. Requests for additional tasks above this limit will either be deferred until later or run on another server.

   • Task Restrictions. Specify the set of tasks that can execute on the server. To do this, select one or more tasks from the list of available tasks. The list of selected tasks can be an inclusion or exclusion list depending on the option you select. You can choose to allow all tasks except those selected in the list (the default behavior), or allow only the selected tasks.

3. Click Save to save your changes to the server settings.

To change the default scheduler settings for Waveset servers, see Editing Default Server Settings. For information about tuning and troubleshooting the scheduler, see Tuning the Scheduler and Tracing the Task Scheduler.

Email Template Server Settings

To configure SMTP server settings, follow the steps under Using the Administrator Interface to Configure Waveset. Select the Email Template tab.

Specify the default email server by clearing the Use Default selection and entering the mail server to use, if other than the default. The text you enter is used to replace the smtpHost variable in Email Templates.

Simple Mail Transfer Protocol (SMTP) is the standard for email transmissions across the Internet.

To change the default SMTP settings for Waveset servers, see Editing Default Server Settings.

Configuring JMX Monitoring

Java Management Extensions (JMX) is a Java technology that allows for managing and/or monitoring applications, system objects, devices, and service oriented networks. The managed/monitored entity is represented by objects called MBeans (for Managed Bean).

This section describes how to configure JMX on an Waveset server so that a JMX client can monitor the system for changes.

You can also configure Waveset to make audit events available using JMX. For information, see The JMX Publisher Type in Oracle Waveset 8.1.1 Business Administrator’s Guide.

Enabling JMX

The JRE did not provide a JMX MBean server prior to Java 1.5, so using JMX required support from the application server. Starting with the Java 1.5 specification, the JRE must provide a built-in MBean server. Consequently, JMX is available from any application server running JRE version 1.5 or later.

Each application server that provides direct JMX support has a different technique for enabling JMX and providing access to the MBeans. You must consult the application server documentation for those instructions.

The MBean server in the JVM is enabled by default, but requires some additional options to be accessed by JConsole or other MBean viewing tools. In most cases, enabling JMX means the application server allows communication on a separate channel with a security profile that is different from that of the HTTP channel. When deciding to enable this channel, you must consider the need to access the MBean data (without restarting the server) against the additional security exposure. Oracle strongly recommends enabling remote JMX access on development and test servers.

For Local Access to MBeans

To enable local access to JMX, where JConsole running on the same host can access MBeans but JConsole running on other hosts cannot, add the following option to the JVM startup:

-Dcom.sun.management.jmxremote

You must decide whether to use this option on production servers based on your security requirements and the need to access the MBean data without restarting the server.

For Remote Access to MBeans

To enable remote access to JMX, where JConsole running on a remote host can access the MBeans but JConsole running on other hosts cannot, add the following options to the JVM startup:

-Dcom.sun.management.jmxremote -Dcom.sun.management.jmxremote.port=<port num>

When you enable remote JMX access, you must carefully consider the security ramifications. For a test server, you can add the following option, which allows non-SSL access to the JMX server without providing any authentication data:

-Dcom.sun.management.jmxremote.authenticate=false

Using this option is very insecure. You should never use this option on a production server, but it might be appropriate for a test server. For more information, consult the following web site: http://download.oracle.com/docs/cd/E17476_01/javase/1.5.0/docs/guide/management/agent.html#jmxagent.

To Configure JMX Polling Settings

The Cluster MBean provided by Waveset has both passive and active operational modes. In active mode, the MBean polls the Waveset repository for additional data and exposes that data through JMX.

Currently, enabling Cluster polling is not recommended because the operational cost of polling is greater than the information provided by the polling. However, if you choose to enable Cluster polling, you can use the following process:

1. Follow the steps described in Using the Administrator Interface to Configure Waveset. Select the JMX tab.

2. Enable JMX cluster polling and configure the interval for the polling threads.

   Use the following options:

   • Enable JMX Cluster Polling. Enables or disables the polling thread for the JMX Cluster MBean. Because system resources are used for polling cycles, enable this option only if you plan to use JMX.

   • Polling Interval (ms). Changes the default interval at which the server polls the repository for changes, when JMX is enabled. Specify the interval in milliseconds.

     The default polling interval is set to 60000 milliseconds. To change it, enter the new value in the entry field provided.

3. Click Save to save changes to the server settings.

With the exception of the Cluster MBean, all other Waveset MBeans are passive, meaning they do not do any additional processing on their own. Most MBeans reflect the values of counters or other variables in the Waveset server. Because they are passive, they add very little processing load to the server.

To Set Java Security Manager MBean Permissions

If you deploy Waveset on an application server that has Java Security Manager enabled, you must add several MBean-related permissions to the application server security policy file, as follows:

grant codeBase "file:${application_server_instance}
      /Oracle Waveset_web_deployment_directory/-" {
    permission javax.management.MBeanServerPermission "*";
    permission javax.management.MBeanPermission "*", "*";
    permission javax.management.MBeanTrustPermission "*";
};

These permissions enable the entire set of Waveset MBean monitoring actions.

If you have a security requirement to disable certain MBean actions, refer to the following web site for more information, http://www.jcp.org/aboutJava/communityprocess/maintenance/jsr003/JMX_1.2_Security_Proposal.pdf.

Filtering Resource MBeans

By default, each Waveset resource has a corresponding JMX MBean that captures the operational statistics of Waveset's interaction with that resource. When an installation has a lot of resources, this may be too much of a good thing, so there is a way to exclude resources and particular operations on resources.

To disable JMX from reporting on different resources or operations on resources follow these steps:

1. Log in to the Waveset admin console.

2. Select the Configuration tab.

3. Select the Servers subtab.

4. Click the Edit Default Server Settings button.

5. Select the JMX tab.

   This page contains two text fields:

   • Use the top field to exclude one or more resources from being monitored by JMX.

     To exclude a resource from JMX monitoring, you must provide a Java regular expression that matches the resource to be excluded. The pattern being compared is in the following form:

     <resource type>:<resource version>:<resource name>

     For example, a regular expression of Database Table:*:Oracle* excludes all resources with a name that starts with Oracle.

   • Use the bottom field to exclude one or more operations (on a set of resources) from being monitored by JMX. To exclude a specific operation from being monitored, you must provide a Java regular expression that matches the operation to be excluded. Operation names are in the following form:

     ACCOUNT_<Operation>

     OBJECT_<Operation>

     ACTION_<Operation>

   The regular expression patterns must match those names. For example:

   • To exclude all operations for non-account objects, enter

     ^OBJECT.*

   • To exclude updates and deletes, enter

     .*UPDATE$

     .*DELETE$

   JMX can monitor these operations:

   ACCOUNT_CREATE ACCOUNT_UPDATE ACCOUNT_DELETE ACCOUNT_GET ACCOUNT_AUTHENTICATE OBJECT_CREATE OBJECT_UPDATE OBJECT_DELETE OBJECT_GET OBJECT_LIST ACTION_RUN

Viewing JMX Data

Because JMX is a Java standard, there are multiple consoles you can use to interact with MBeans. The Java 1.5 JDK provides the JConsole utility, which is a graphical MBean console that is well suited for displaying Waveset MBean data. JConsole can show the current static value of MBean attributes and it can chart individual (numeric) attributes over time. JConsole charts MBean attributes by periodically polling the MBean for its current value and displaying the attributes as a line chart.

Using JConsole Locally

Using JConsole to view a local server is as simple as starting JConsole and selecting the application server process from a list. When JConsole displays the new connection dialog, it scans the local host for any Java processes that offer an MBean server. Local JConsole connections connect to a local process. These connections are only possible when JConsole is running on the same host as the application server. If your application server does not show up in JConsole's local process list, you probably have not enabled JMX (see Enabling JMX).

Using JConsole Remotely

Assuming you started the JVM with the settings that allow remote MBean access, you can access a remote server's MBean by starting JConsole and connecting to a remote process. The exact Uniform Resource Identifier (URI) used to connect to the remote server depends on how you enabled remote JMX access. The URI is typically one of the following:

• hostname:port (if remote access was granted with the options shown above)

• service:jmx:rmi://host:port/jndi/...

Again, refer to your application server documentation for more information about how to remotely connect to the MBean server. If you have problems connecting JConsole to the application server, check the following URL for more information: http://download.oracle.com/docs/cd/E17476_01/javase/1.5.0/docs/guide/management/faq.html

You can view the structure (but not the data) of the Waveset-provided MBean by going to the following debug page (http://host:port/Oracle Waveset/debug) and clicking the Show MBean button.

For more information on JMX, visit this website:

http://www.oracle.com/technetwork/java/javase/tech/index.html

Data Exposed in JMX

So what kind of data does Waveset expose using JMX MBeans? The following table contains a list of MBeans, describes the data they provide, and explains how to use that data.

Every application server also provides a number of useful MBeans. These MBeans typically supply information about the application server's processing elements such as HTTP processing, DataSource operations, classloading, and JSP compilation. If you have never browsed the MBeans provided by your application server, consider doing so.

Editing Default Server Settings

The Default Server Settings feature lets you set the default settings for all Waveset servers. The servers inherit these settings unless you select differently in the individual server settings pages.

To Edit the Default Server Settings

1. In the Administrator interface, click Configure -> Servers.

   The Configure Servers page opens.

2. Click Edit Default Server Settings.

   The Edit Default Server Settings page opens.

   The Edit Default Server Settings page displays the same options as the individual server settings pages. For help, refer to the documentation for the individual server settings pages.

   Changes you make to each default server setting is propagated to the corresponding individual server setting, unless you have deselected the Use default option for that setting.

   Click Save to save changes to the server settings.