JacORB Chapter 3_01

3 Configuration

This chapter explains the general mechanism for configuring JacORB and lists all configuration properties. Note that ORB configuration has changed from version 2.1 to 2.2, in particular the names and locations of the standard configuration files.

If you are upgrading from a previous version, please note that JacORB will still work with the old files, but you will have to copy your existing jacorb.properties file to JacORB_HOME/etc/jacorb.properties, or rename it to orb.properties if you want it loaded from your user home directory as before.

3.1 Properties

JacORB has a number of configuration options which can be set as Java properties. There are three options for setting properties:

• in properties files
• as command line properties, and
• as properties passed as arguments to ORB.init() in the code of your applications.

In the case of a single JVM with multiple ORB instances, it may be required to either share configuration options between ORBs, or to separate the individual configurations from each other. We explain how properties can be set for sharing or for individual ORB instances.

3.1.1 Properties files

JacORB looks for a few standard properties files, a common file called orb.properties, and an ORB-specific file called <orbid>.properties, where <orbid> is the name of an ORB instance that was explicitly configured. Moreover, JacORB can load custom properties files from arbitrary locations. We explain each of these files in turn.

The common properties file

The reason for having a common properties file is that a single JacORB installation may be shared by a number of users with a set of common default properties. These may be refined by users in their own properties files but still provide reasonable defaults for the environment. Note that it is not required to have a common properties file as all configuration options can also be set in other files, on the commandline or in the code.

JacORB looks for the common properties file orb.properties in the following places:

1. in the lib directory of the JDK installation. (The JDK’s home directory denoted by the system property ”java.home”).
2. in the user home directory. (This is denoted by the system property ”user.home”. On Windows, this is c:\documents\username, on Unixes it’s ˜user. If in doubt where your home directory is, write a small Java programm that prints out this property.
3. on the class path.

   The common properties file is searched in the order presented above, so you may actually be loading multiple files of this name. If a properties file is found it is loaded, and any property values defined in this file will override values of the same property that were loaded earlier. Loading properties files from the classpath is useful when distributing applications packaged in JAR files.

The ORB properties file

Having ORB-specific properties files is necessary when multiple ORB instances live in the sameprocess, but need to have separate configurations, e.g., some ORBs use SSL and others don’t, or some ORBs need to listen on separate but predefined ports. To let colocated ORBs use and retrieve separate configurations, JacORB provides a lookup mechanisms based on a specific property, the ORBid property. The default value for the ORBid is jacorb, ie. is the ORBid is not explicitly set anywhere, it defaults to jacorb. Note that this ORBid is reserved, ie., you cannot explicitly set your ORBid to this value. To use different configurations for different ORBs, you simply pass different ORBid values to your ORBs.

JacORB looks for ORB properties files in these places:

1. jacorb.config.dir/etc/orbid.properties., if that exists, or
2. jacorb.home/etc/orbid.properties., or
3. the current directory (’./orbid.properties.’)
4. on the class path.

The jacorb.config.dir and jacorb.home properties must be set for JacORB to be able to use a preconfigured configuration directory. The jacorb.home property defaults to ‘‘.’’, if unset. Setting these properties can be done in the orb.properties file, or bypassing a property in on the commandline, like this:

$ jaco -Djacorb.config.dir=c:/ -DORBid=example test.Example

This commandline causes JacORB to look for a file called example.properties in c:/etc. If the -DORBid=example had been ommitted, the name of the ORB properties file that JacORB would try to load would have been jacorb.properties, because that is the default value for the ORBid. A good starting point is to have a common properties file that sets the jacorb.config.dir property, and then have put a jacorb.properties file in that directory.

Note, however, that the added flexibility of using multiple configuration files may lead to individual properties defined in multiple files. You must know the order in which your configuration files are loaded to avoid confusion over property settings not having the expected effect! For this reason, JacORB outputs log messages to the terminal that show the names of the properties files as they are loaded. This log message always goes to the terminal because the actual JacORB logging is not yet configured at this stage. It can be suppressed by setting the jacorb.config.log.verbosity property to a value below 3.

Custom properties files

In addition to the standard JacORB properties files, a custom properties file can be loaded by passing the name of that properties files the custom.props property to JacORB. This can be handy for application-specific settings that you want to distribute with your code.

The value of this property is the path to a properties file, which contains the properties you want to load. As an example, imagine that you usually use plain TCP/IP connections, but in some cases want to use SSL (see section 11). The different ways of achieving this are

• Use just one properties file, but you will have to edit that file if you want to switch between SSL and plaintext connections.
• Use commandline properties exclusively (cf. below), which may lead to very long commands
• Use a command property file for all applications and different custom properties files for each application.

For example, you could start a JacORB program like this:

$jaco -Dcustom.props=c:/tmp/ns.props org.jacorb.naming.NameServer

In addition to loading any standard properties files found in the places listed above, JacORB will now also load configuration properties from the file c:/tmp/ns.props, but this last file will be loaded after the default properties files and its values will thus take precedence over earlier settings.

3.1.2 Command-line properties

In the same way as the custom.props property in the example above, arbitrary other Java properties can be passed to JacORB programs using the -D<prop name>=<prop value> command line syntax for the java interpreter, but can be used in the same way with the jaco script. Note that the properties must precede the class name on the command line. For example to override the ORB initial references for NameService the following may be used:

jaco -DORBInitRef.NameService=file:///usr/users/...../NameService.ior Server

The ORB configuration mechanism will give configuration properties passed in this way precedence over property values found in configuration files.

Anything that follows after the class name is interpreted (by java) as a command line argument to the class and will be visible in the args parameter of the classes main method. For example

jaco Server -ORBInitRef.NameService=file:///usr/users/..../NameService.ior

3.1.3 Arguments to ORB.init()

For more application–specific properties, you can pass a java.util.Properties object to ORB.init() during application initialization. Properties set this way will override properties set by a properties file. The following code snippet demonstrates how to pass in a Properties object (args is the String array containing command line arguments):

java.util.Properties props = new java.util.Properties();

props.setProperty("jacorb.implname","StandardNS");

org.omg.CORBA.ORB orb = org.omg.CORBA.ORB.init(args, props);

3.2 Common Configuration Options

We are now ready to have a look at the most basic JacORB configuration properties. As a starting point, you should look at the file /etc/jacorb_properties.template, which you can adapt to your own needs.

3.2.1 Initial references

Initial references are object references that are available to CORBA application through the bootstrap orb.resolve_initial_service() API call. This call takes a string argument as the name of an initial reference and returns a CORBA object reference, e.g., to the initial name service.

########################################

# #

# Initial references configuration #

# #

########################################

#

# URLs where IORs are stored (used in orb.resolve_initial_service())

# DO EDIT these! (Only those that you are planning to use,

# of course ;-).

#

# The ORBInitRef references are created on ORB startup time. In the

# cases of the services themselves, this may lead to exceptions being

# displayed (because the services aren’t up yet). These exceptions

# are handled properly and cause no harm!

#ORBInitRef.NameService=corbaloc::160.45.110.41:38693/StandardNS/NameServer-POA/_#ORBInitRef.NameService=file://c:/NS_Ref

ORBInitRef.NameService=http://www.x.y.z/˜user/NS_Ref

#ORBInitRef.TradingService=http://www.x.y.z/˜user/TraderRef

The string value for ORBInitRef.NameService is a URL for a resource used to set up the JacORB name server. This URL will be used by the ORB to locate the file used to store the name server’s object reference (see also chapter 5).

3.2.2 Logging

JacORB uses external log kit implementations for writing logs. The default log kit is the Apache LogKit implementation. To plug in another logger, a developer must implement the org.jacorb.util.LoggerFactory interface and supply that class name as the value of the jacorb.log.loggerFactory property.

The interface is

package org.jacorb.util;

public interface LoggerFactory

String getLoggingBackendName();

Logger getNamedLogger(String name);

Logger getNamedRootLogger(String name);

Logger getNamedLogger(String name, String fileName, long maxFileSize)

void setDefaultLogFile(String fileName, long maxLogSize)

The new factory must return Loggers that implement org.apache.avalon.framework.logger.Logger. An example is provided (See org.jacorb.util.ConsoleLogger) which simply uses org.apache.avalon.framework.logger.ConsoleLogger to output to the terminal e.g.

public class ConsoleLoggerFactory implements LoggerFactory

public ConsoleLoggerFactory()

{

target = new ConsoleLogger();

}

...

public Logger getNamedLogger(String name)

{

return target;

}

...

Log levels and different log components

The JacORB logging mechanism can be fine-tuned to set different log levels for different components of JacORB. It is still possible to rely only on one single, default log level. This log level is specified like this (note that the properties have changed from previous JacORB versions!):

##################################

# #

# Default Logging configuration #

# #

##################################

# Name of the factory class that plugs in a given log kit

# The default value is JacORB’s own factory for the Apache

# LogKit. Only edit (or uncomment) if you want a different

# log kit.

#jacorb.log.loggerFactory=org.jacorb.util.LogKitLoggerFactory

# log levels:

#

# 0 = fatal errors only = "almost off" (FATAL ERRORS)

# 1 = non-fatal errors and exceptions (ERROR)

# 2 = important messages (WARN)

# 3 = informational messages and exceptions (INFO)

# 4 = debug-level output (DEBUG) (may confuse the unaware user :-)

jacorb.log.default.verbosity=3

For other components, the individual log levels are set using log properties specific to that component, e.g.,

jacorb.naming.log.verbosity=0

will turn logging off for the naming service, but all other parts of the ORB will still use the default log level. The general pattern for the log level property is jacorb.<component>.log.verbosity. Currently available logging components are

• activator
• jacorb.giop
• jacorb.giop.conn
• iiop.conn
• imr.locate
• imr.state
• naming
• orb
• orb.singleton
• orb.basic
• orb.factory
• orb.iiop
• orb.interceptors
• poa
• SAS
• SAS.CSS
• SAS.GSSUP
• SAS.TSS
• security
• security.jsse
• util.tpool

Logging output to a file

The properties specific to file logging are the following:

# where does output go? Terminal is default

jacorb.logfile=c:/tmp/jacorb.log

# filename for logging from the singleton ORB

# the file will be placed in the same directory

# as jacorb.logfile

jacorb.logfile.singleton=orbsingleton

# Append to an existing log file or overwrite? (Applies to

# file logging only)

jacorb.logfile.append=on

# If jacorb.logfile.append is on, set rolling log size in kilobytes.

# A value of 0 implies no rolling log

jacorb.logfile.maxLogSize=0

Unless the jacorb.logfile property is set to a file name, output will be sent to the terminal. If the jacorb.logfile property ends in $implname e.g. jacorb.logfile=c:/tmp/$implname and the jacorb.implname property has been set, output will be logged to a file with the same name as the jacorb.implname property value. See section 3.3.1 for more information on the jacorb.implname property. The jacorb.logfile.append value tells the logger whether to overwrite existing log files or to append to the existing log file. The jacorb.logfile.maxLogSize property, finally, determines how large a log file may become before the logger automatically creates a new file. This value is in kilobytes. If it is set to 0, log files may become arbitrarily large, no log file rotation is used. If the value of jacorb.logfile ends with the special string $implname, this postfix will be replaced with the current ImplName of the ORB that uses the logging. See 3.3.1 for more details about ImplName.

Note that the singleton ORB is treated in a special way. To enable filelogging for it, you needto additionally set the property jacorb.logfile.singleton to a filename. If the property jacorb.logfile includes a directoryname, the singleton ORB logfile will get this directory prepended. Otherwise its plain value will be used. A timestamp will be appended so that logging to the same directory won’t clash. Also the suffix .log will be appended.

The jacorb.poa.monitoring property determines whether the POA should bring up a monitoring GUI for servers that let you examine the dynamic behavior of your POA, e.g. how long the request queue gets and whether your thread pool is big enough. Also, this tool lets you change the state of a POA, e.g. from active to holding. Please see chapter 6 on the POA for more details.

The singleton ORB will use the logging component jacorb.orb.singleton for logging.