|
| Sun ONE Connector Builder 2.0 Developer's Guide |
Administration and Monitoring of the Generated Resource AdapterThis module describes the following topics:
You can administer and monitor resource adapters you have generated and deployed. In addition to whatever features the deployment environment itself might provide, resource adapters you generate using the Connector Builder have their own additional administration and monitoring features: logging and connection pooling.
Logging
The logging mechanism of the Connector Builder provides a common logging framework that allows the resource adapter - its generated code, its customized logic, and its core runtime - to log messages in a uniform and standard way.
All the output from the resource adapter is sent through its logging mechanism. This mechanism can be configured using the log properties file.
The key features are:
- Controls logging at fine granularity, so that logging can be enabled or disabled based on the severity of messages.
- Provides support for logging localized and parameterized messages.
- Provides support for multiple output destinations.
- Allows enabling or disabling of logging at runtime.
- Highly configurable through Java-style properties file.
Adapter Log Configuration File
By default, Connector Builder generates a log configuration file with file name <AdapterLogicalName>log.properties. The generated configuration file is located under src directory of the generated adapter directory structure. The generated file contains default logging settings, and you can adjust these settings to alter the default logging behavior before preparing for packaging the resource adapter.
During deployment of a resource adapter in non-managed environment, the adapter log configuration file is extracted from rar file and placed under <CB_DEPLOY_ROOT>/<adaptername>/config directory. The deployment process also modifies the base directory and log file name pointing it to the deployed environment.
The <CB_DEPLOY_ROOT> is defined as follows:
For iPlanet Application Server 6.5: <iASInstallDir>/ias/APPS/icb
For iPlanet Web Server 6.0: <iWSInstallDir>/plugins/icb
Log Configuration Parameters
The following logging parameters can be configured:
- Log Level
- List of Handlers (logging output destinations)
- StreamHandler Configurable Parameters
- FileHandler Configurable Parameters
Log Level
The log level defines a set of standard logging levels that can be used to control logging output. The log levels are ordered and are specified by ordered integers. Enabling logging at a given level also enables logging at all higher levels. Each log message sent from Connector Builder to the logging framework has an associated log level. The logging framework sends the message to a handler only if the message's log level is the same or higher than:
- the global log level,
- the handler's log level
This is true even if the handlers specify a lower log level setting than the global one. For example, if the global log level setting is WARNING and a handler specifies DEBUG, no debug messages are sent to that handler because the global log level filters them out first.
The following table describes the Log Level configurable values. The left column lists the parameters and the right column lists the value.
Log Level Configuration Parameters
Description
Value
Valid Values
ERROR, WARNING, INFO, DEBUG, OFF
Default Value
WARNING
Parameter Name
icon.logging.level
Example: icon.logging.level=ERROR
The supported log levels are listed in the following table. The right column lists the log level and the left column provides a description.
List of Handlers (logging output destinations)
The following handlers that log output destinations are supported:
- StreamHandler - Messages that are written to an output stream.
- FileHandler - Messages that are sent to a file.
You can specify more than one output destination separated by a white space. The log handler configuration values are listed in the following table. The left column lists a description of the parameter. The right column lists the value.
List of Log Handlers Parameters
Description
Value
Valid Value
StreamHandler, FileHandler
Default Value
FileHandler
Parameter Name
icon.logging.handlers
Example: icon.logging.handlers= StreamHandler FileHandler
StreamHandler Configurable Parameters
Use either the standard-out or standard-error output stream.
The StreamHandler output-stream configuration parameters are described in the following table. The left column lists a description of the parameter. The right column lists the value.
Configurable Parameters for StreamHandler Output
Description
Value
Valid Values
OUT, ERR
Default Value
OUT
Property Name
icon.logging.StreamHandler.output
Example: icon.logging.StreamHandler.output=OUT
StreamHandler Log Level (optional)
By default the log level for StreamHandler is left blank. The logging framework assigns the global log level to this log handler. This default behavior can be modified by specifying a log level to StreamHandler.The following table describes the StreamHandler Log Level configurable parameters. The left column provides A description of the parameter. The right column lists the value.
Configurable Parameters for StreamHandler Log Level
Description
Value
Valid Values
ERROR, WARNING, INFO, DEBUG, OFF
Default Value
Property Name
icon.logging.SteamHandler.level
FileHandler Configurable Parameters
FileHandler Log Level (Optional)
By default the log level for FileHandler is left blank. The logging framework assigns the global log level to this log handler. This default behavior can be modified by specifying a log level to FileHandler. The following table describes the FileHandler Log Level configurable parameters. The left column provides description of the parameter. The right column lists the value.
Configurable Parameters for FileHandler Log Level
Description
Value
Valid Values
ERROR, WARNING, INFO, DEBUG, OFF
Default Value
Parameter Name
icon.logging.FileHandler.level
For example: icon.logging.FileHandler.level=WARNING
Base Directory for Log File
The following table describes the base directory for the log-file configuration parameters. The left column provides description of the parameter. The right column lists the value.
Example: icon.logging.FileHandler.basedir= /export/home/iplanet/ias6/APPS/icb/logs for Application Server 6.5
Base Name of Log File
The following table describes the base name of the log-file configuration parameter. The left column lists a description of the parameter. The right column lists the value.
Configuration Parameters for Log File Name
Description
Value
Valid Values
Any valid file name
Default Value
<AdapterLogicalName>.log
Property Name
icon.logging.FileHandler.filename
Example: icon.logging.Filehandler.filename=COTS.log
Append mode
If this flag is set it true, the log file is opened in append mode. New messages are added at end of an existing log file. If this flag is set it to false, the log files are initialized on restart of the server.
The following table describes the append mode configuration parameter. The left column lists a description of the parameter. The right column lists the value.
Configuration Parameters for FileHandler Append
Description
Value
Valid Values
true, false
Default Value
true
Property Name
icon.logging.FileHandler.append
Sample Adapter Log Configuration File
The Sample Adapter Log Configuration File code example displays a sample log configuration file generated for sample resource adapter COTS
Logging APIs
All parts of the resource adapter that Connector Builder provides - both the common run-time logic and the generated classes - use the logging framework. In addition, customizations to the generated code may also use the framework for its own logging.
Any logic in the resource adapter that needs to perform logging invokes methods on ICONLogger objects. Each log message has an associated log level. Each logger keeps track of a set of output destination handlers.
You can configure these parameters using the log properties file. Both loggers and handlers may use logging levels to decide if they are interested in a particular message. The APIs are structured so that calls on the Logger API are low cost when logging is disabled.
The logging framework can be accessed using the following two classes, which are located in the package com.sun.appinteg.adapter.util:
ICONLogger
The ICONLogger class is the main interface to the Connector Builder logging framework. It provides numerous convenience methods for logging messages.
The following are examples of the ICONLogger API:
- logger.log(ICONLogLevel.INFO, "This is an info message");
- logger.log(ICONLogLevel.WARNING, "File {0} not found", file);
The ICON Logger API also provides methods to accept exceptions for which stack traces can be logged.
ICONLogLevel
The ICONLogLevel class defines a set of standard logging levels that can be used to control logging output. The log levels are ordered and are specified by ordered integers. ICONLogLevel enables logging at a given level also enables logging at all higher levels. This is a convenience class to use log levels defined in the Connector Builder logging framework. The adapter developer normally uses the above two interfaces in the logging framework to log messages.
Refer to API Javadoc available under <connector_builder_install_root>/docs/api directory for more details.
How to Access a Logger Instance within Generated Adapter Code
The logger instance is associated with each resource adapter and uniquely identified by adapter logical name within a single Java VM. All connection factory instances of a specific resource adapter use the same logger. This logger is automatically initialized by taking adapter log configuration file, and adapter message bundle. The resource adapter developer doesn't need to perform any additional customization to initialize the logger. The logger instance is accessible from the following CCI and SPI interfaces of a generated resource adapter:
- ManagedConnectionFactory.getLogger()
- ManagedConnection.getLogger()
- ConnectionFactory.getLogger()
- Connection.getLogger()
- Interaction.getLogger()
Refer to Javadoc available under <connector_builder_install_root>/docs/api directory for more details.
Logging by Generated Resource Adapters
The generated code performs logging as shown in the following table. The right column lists the generated class. The middle column lists the generated method. The right column lists the logging performed.
Connection Pooling
According to the J2EE Connector Architecture version 1.0 specification, connection pooling support in a non-managed environment is optional. The specification mandates connection pooling support in the managed environment, which is provided by the application server. The resource adapters can optionally provide pooling support in non-managed environment.
The resource adapters built using Connector Builder support, by default, connection pooling in a non-managed environment. Users can take advantage of connection pooling when the resource adapters built using Connector Builder are deployed into iPlanet Application Server 6.5 or iPlanet Web Server 6.0.
Pool Configuration Parameters
The behavior of connection pool per resource adapter can be controlled by adjusting the following pool parameters:
- maxPoolSize - maximum number of objects allowed in the pool
- steadyPoolSize - the number of unused objects in the pool until reached the maximum unused life.
- maxWait - the maximum time, in seconds, a request for an object waits before timeout.
- unusedMaxLife - the maximum time, in seconds, that an object is in the pool until it is destroyed.
All the generated resource adapters using Connector Builder, by default, set the following pooling parameters:
- maxPoolSize = 32
- steadyPoolSize = 4
- maxWait = 10
- unusedMaxLife = 1000
The above information is stored in sun-ra.xml file, which is generated automatically and packaged with the resource adapter.
To Modify Pool Parameters
You must use `icconfig' command to query and update the pool parameters associated with a connection factory of a resource adapter.
- Use the following command to query existing pool parameters:
icconfig query -s <reg_server_name> -n <lookupname>
For example: icconfig query -s myias65 -n COTS
- Use the following command to update an existing pool parameter:
icconfig update -s <reg_server_name> -n <lookupname> -p <poolparam=value>
For example: icconfig update -s myias65 -n COTS -p maxPoolSize=32 -p steadyPoolSize=20
- Restart the server to have the changes take effect.