%
% $Id: configuration.tex,v 1.18 2006/06/01 13:26:07 alphonse.bendt Exp $
%

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 {\tt jacorb.properties} file to {\tt
  JacORB\_HOME/etc/jacorb.properties}, or rename it to {\tt
  orb.properties} if you want it loaded from your user home directory
as before.

\section{Properties}

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

\begin{itemize}
\item in properties files
\item as command line properties, and
\item as properties passed as arguments to ORB.init() in the code of your
  applications.
\end{itemize}

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.

\subsection{Properties files}

JacORB looks for a few standard properties files, a common file called
{\tt orb.properties}, and an ORB-specific file called {\tt
  <orbid>.properties}, where {\tt <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.

\subsubsection{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 {\tt orb.properties} in
the following places:

\begin{enumerate}
\item in the {\tt lib} directory of the JDK installation. (The JDK's
  home directory denoted by the system property "java.home").
\item in the user home directory. (This is denoted by the system
    property "user.home". On Windows, this is
    {\verb+c:\documents\username+}, on Unixes it's {\verb+~user+}. If
    in doubt where your home directory is, write a small Java programm that
  prints out this property.
\item on the class path.
\end{enumerate}

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.

\subsubsection{The ORB properties file}

Having ORB-specific properties files is necessary when multiple ORB
instances live in the same process, 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 {\tt ORBid} property. The
default value for the ORBid is {\tt jacorb}, ie. is the ORBid is not
explicitly set anywhere, it defaults to {\tt 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:

\begin{enumerate}
\item {\tt jacorb.config.dir/etc/orbid.properties.}, if that exists, or
\item {\tt jacorb.home/etc/orbid.properties.}, or
\item the current directory ({\tt './orbid.properties.'})
\item on the class path.
\end{enumerate}

The {\tt jacorb.config.dir} and {\tt jacorb.home} properties must be
set for JacORB to be able to use a preconfigured configuration
directory. The {\tt jacorb.home} property defaults to {\tt ``.''}, if
unset. Setting these properties can be done in the {\tt
  orb.properties} file, or by passing a property in on the
commandline, like this:

\cmdline{jaco -Djacorb.config.dir=c:/ -DORBid=example test.Example}

This commandline causes JacORB to look for a file called {\tt
  example.properties} in {\tt c:/etc}. If the {\tt -DORBid=example}
had been ommitted, the name of the ORB properties file that JacORB
would try to load would have been {\tt 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 {\tt jacorb.config.dir}
property, and then have put a {\tt 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 {\tt jacorb.config.log.verbosity} property
to a value below 3.

\subsubsection{Custom properties files}

In addition to the standard JacORB properties files, a {\em custom
  properties file} can be loaded by passing the name of that
properties files the {\tt 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 \ref{ch:SSL}). The different ways of achieving
this are

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

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

\cmdline{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 {\tt 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.

\subsection{Command-line properties}

In the same way as the {\tt custom.props} property in the example
above, arbitrary other Java properties can be passed to JacORB
programs using the {\tt -D<prop name>=<prop value>} command line
syntax for the {\tt java} interpreter, but can be used in the same way
with the {\tt 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:

\small{
\begin{verbatim}
    jaco -DORBInitRef.NameService=file:///usr/users/...../NameService.ior
        Server
\end{verbatim}

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 {\tt java}) as a
command line argument to the class and will be visible in the {\tt args}
parameter of the classes main method. For example

\small{
\begin{verbatim}
    jaco Server
        -ORBInitRef.NameService=file:///usr/users/..../NameService.ior
\end{verbatim}

\subsection{Arguments to ORB.init()}

For more application--specific properties, you can pass a {\tt
 java.util.Properties} object to {\tt 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 {\tt Properties} object ({\tt args} is the String array
containing command line arguments):

\small{
\begin{verbatim}
    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);
\end{verbatim}
}

\section{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 {\tt
  /etc/jacorb\_properties.template}, which you can adapt to your own
needs.

\subsection{Initial references}

Initial references are object references that are available to CORBA
application through the bootstrap {\tt
  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.

\renewcommand{\baselinestretch}{0.9}
\small{
\begin{verbatim}
########################################
#                                      #
#   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/_root
#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
\end{verbatim}
}
\renewcommand{\baselinestretch}{1.0}
\small\normalsize

The  string value  for  {\tt
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 \ref{ch:naming}).

\subsection{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 {\tt org.jacorb.util.LoggerFactory} interface and supply that
class name as the value of the {\tt jacorb.log.loggerFactory} property.
%%% filbreak is to keep the description of the verbatim with it.
\filbreak
The interface is
\begin{small}
\begin{verbatim}
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)
\end{verbatim}
\end{small}

The new factory must return Loggers that implement
{\tt org.apache.avalon.framework.logger.Logger}. An example is provided (See
{\tt org.jacorb.util.ConsoleLogger}) which simply uses
{\tt org.apache.avalon.framework.logger.ConsoleLogger} to output to the terminal e.g.
\begin{small}
\begin{verbatim}
public class ConsoleLoggerFactory implements LoggerFactory
    public ConsoleLoggerFactory()
    {
        target = new ConsoleLogger();
    }
...
    public Logger getNamedLogger(String name)
    {
        return target;
    }
...
\end{verbatim}
\end{small}

\subsubsection*{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!):

\renewcommand{\baselinestretch}{0.9}
\small{
\begin{verbatim}
##################################
#                                #
#  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
\end{verbatim}
}
\renewcommand{\baselinestretch}{1.0}
\small\normalsize

For other components, the individual log levels are set using log
properties specific to that component, e.g.,\\
\\
{\tt 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 {\tt jacorb.<component>.log.verbosity}.
Currently available logging components are
\begin{small}
\begin{itemize}
\item activator
\item jacorb.giop
\item jacorb.giop.conn
\item iiop.conn
\item imr.locate
\item imr.state
\item naming
\item orb
\item orb.singleton
\item orb.basic
\item orb.factory
\item orb.iiop
\item orb.interceptors
\item poa
\item SAS
\item SAS.CSS
\item SAS.GSSUP
\item SAS.TSS
\item security
\item security.jsse
\item util.tpool
\end{itemize}
\end{small}

\subsubsection*{Logging output to a file}

The properties specific to file logging are the following:

\renewcommand{\baselinestretch}{0.9}
\small{
\begin{verbatim}
# 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
\end{verbatim}
}
\renewcommand{\baselinestretch}{1.0}
\small\normalsize

Unless the {\tt jacorb.logfile} property is set to a file name, output
will be sent to the terminal. The {\tt jacorb.logfile.append} value
tells the logger whether to overwrite existing log files or to append
to the. The {\tt 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 {\tt 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 \ref{implname} for more details about ImplName.

Note that the singleton ORB is treated in a special way. To enable filelogging for it,
you need to additionally set the property {\tt jacorb.logfile.singleton} to a filename.
If the property {\tt 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  {\tt 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 {\it active}  to {\it holding}.
Please see chapter \ref{ch:POA} on the POA for more details.

The singleton ORB will use the logging component {\tt jacorb.orb.singleton} for
logging.

\section{Configuration Properties}

A comprehensive listing and description of the properties which are used
to configure JacORB are given in the following tables.

\begin{small}
\begin{longtable}{|p{5cm}|p{7.5cm}|p{1.5cm}|p{1.5cm}|}
\caption{ORB Configuration}\\
\hline
~ \hfill \textbf {Property} \hfill ~ & ~ \hfill \textbf {Description}
\hfill ~ & ~ \hfill \textbf {Type} \hfill ~ & \hfill \textbf{Default} \endhead
\hline
\verb"ORBInitRef.<service>" & Properties of this form configure
initial service objects which can be resolved via the ORB
resolve\_initial\_references. A variety of URL formats are
supported. & URL & unset \\
\hline
\verb"org.omg.PortableInterc"
\verb"eptor.ORBInitializerCl"
\verb"ass.<name>" & A portable interceptor initializer class
instantiated at ORB creation. & class & unset \\
\hline
\verb"jacorb.orb.objectKeyMa"
\verb"p.<name>" & Maps an object key to an arbitrary string thereby
enabling better readability for corbaloc URLs. & string & \\
\hline

\verb"jacorb.giop_minor_vers"
\verb"ion" & The GIOP minor version number to use for newly created
IORs & integer & 2 \\
\hline
\verb"jacorb.retries" & Number of retries if connection cannot
directly be established & integer & 5 \\
\hline
\verb"jacorb.retry_interval" & Time in milliseconds to wait between
retries & millisec. & 500 \\
\hline
\verb"jacorb.maxManagedBufSi"
\verb"ze" & This is NOT the maximum buffer size that can be used, but
just the largest size of buffers that will be kept and managed. This
value will be added to an internal constant of 5, so the real value in
bytes is 2** (5 + maxManagedBufSize - 1). You only need to increase
this value if you are dealing with LOTS of LARGE data structures. You
may decrease it to make the buffer manager release large buffers
immediately rather than keeping them for later reuse & integer & 18 \\
\hline
\verb"jacorb.bufferManagerFl"
\verb"ushMax" & Whether to use an additional unlimited size buffer
cache for CDROutputStreams. If -1 then off, if zero then this is
feature is enabled, if greater than zero then it is enabled and
flushed every x seconds & integer & -1 \\
\hline
\hline
\verb"jacorb.connection.clie"
\verb"nt.pending_reply_timeo"
\verb"ut" &  Wait the specified number of msecs for a reply to a
request. If exceeded, a org.omg.CORBA.TIMEOUT exception will be
thrown. Not set by default & millisec. & 0  \\
\hline
\verb"jacorb.connection.clie"
\verb"nt.idle_timeout" & Client-side timeout. This is set to non-zero in order
to stop blocking after specified number of milliseconds & millisec. &
unset \\
\hline
\verb"jacorb.connection.clie"
\verb"nt.timeout_ignores_pen"
\verb"ding_messages" & Controls if client-side idle timeouts take care of
pending messages or not. & boolean & \\
\hline
\verb"jacorb.connection.clie"
\verb"nt.retry_on_failure" & Controls if network failures on existing connections
should yield a COMM\_FAILURE or should trigger a remarshaling
of all pending messages. & boolean & \\
\hline
\verb"jacorb.connection.serv"
\verb"er.timeout" & Maximum time in milliseconds that a server keeps a
connection open if nothing happens & millisec. & unset \\
\hline
\verb"jacorb.connection.max"
\verb"_server_connections" & This property sets the
  maximum number of TCP/IP connections that will be listened on by the
  server--side ORB & integer & unlimited \\
\hline
\verb"jacorb.connection.wait"
\verb"_for_idle_interval" & This property sets the
  interval to wait until the next try is made to find an idle connection to
  close & millisec & 500\\
\hline
\verb"jacorb.connection.sele"
\verb"ction_strategy_class" & This property sets
  the {\tt Selection\-Strategy} & class & \\
\hline
\verb"jacorb.connection.stat"
\verb"istics_provider_class" & This property sets
  the {\tt Statistics\-Provider} & class & \\
\hline
\verb"jacorb.connection.del"
\verb"ay_close" & This property controls the behaviour after sending a GIOP
CloseConnection messsage. If set to ``on'', the TCP/IP connection won't be
closed directly. Instead, it is waited for the client to do so
first & boolean & off \\
\hline
\hline
\verb"jacorb.transport.facto"
\verb"ries" & This property controls which transport plug-ins are
available to the ORB.  The value is a list of classes that implement the ETF
{\tt Factories} interface.
& comma-separated list of classes & \\
\hline
\verb"jacorb.transport.serve"
\verb"r.listeners" & Controls which transports should be offered by
JacORB on the server side.  The value is a list of numeric profile
tags for each transport that should be available on the server side.
& comma-separated list of integers & \\
\hline
\verb"jacorb.transport.clien"
\verb"t.selector" & Name of a class that selects the transport profile
to use for communication on the client side.  The value is the fully
qualified name of a class that implements {\tt
  org.jacorb.orb.ProfileSelector}.
& class & \\
\hline
\verb"jacorb.reference_cachi"
\verb"ng" & Whether or not JacORB caches objects references & boolean & unset  \\
\hline
\verb"jacorb.hashtable_class" & The following property specifies the
class which is used for reference caching. WeakHashtable uses
WeakReferences, so entries get garbage collected if only the Hashtable
has a reference to them. This is useful if you have many references to
short-living non-persistent CORBA objects. It is only available for
java 1.2 and above. On the other hand the standard Hashtable keeps the
references until they are explicitly deleted by calling
\_release(). This is useful for persistent and long-living CORBA
objects & class & Hashtable \\
\hline
\verb"jacorb.use_bom" & Use GIOP 1.2 byte order markers, since CORBA
2.4-5 & boolean & off  \\
\hline
\verb"jacorb.giop.add_1_0_pr"
\verb"ofiles" & Add additional IIOP 1.0 profiles even if using IIOP
1.2 & boolean & off \\
\hline
\verb"jacorb.dns.enable" & Use DNS names in IORs, rather than numeric
IP addresses & boolean & off \\
\hline
\verb"jacorb.compactTypecode"
\verb"s" & Whether to send compact typecodes. Options are 0 (off), 1
(Partial compaction), 2 (full compaction of all optional parameters) & integer & 2 \\
\hline
\verb"jacorb.cacheTypecodes" & Whether to cache read
typecodes  & boolean & off \\
\hline
\verb"jacorb.cachePoaNames" & Whether to cache scoped poa
names & boolean & off \\
\hline
\verb"jacorb.orb_initializer"
\verb".fail_on_error" & Control, if failing ORBInitializers should make the
complete {\tt ORB.init()} fail. & boolean & off \\
\hline
\verb"jacorb.interop.indirec"
\verb"tion_encoding_disable" & Turn off indirection encoding for
repeated typecodes. This fixes interoperability with certain broken
ORB's eg. Orbix 2000 & boolean & off \\
\hline
\verb"jacorb.interop.comet" & Enable additional buffer length checking
and adjustment for interoperability with Comet CORBA/COM bridge which
can incorrectly encode buffer lengths & boolean & off
\\
\hline
\verb"jacorb.interop.lax_"
\verb"boolean_encoding" & Treat any non zero CDR encoded boolean value
as true (strictly should be 1 not non zero). This is useful for ORBs such
as VisiBroker and ORBacus & boolean & off \\
\hline
\verb"org.omg.PortableInterc"
\verb"eptor.ORBInitializerCl"
\verb"ass.bidir_init" & This portable interceptor must be configured
to support bi-directional GIOP & class & unset \\
\hline
\verb"jacorb.ior_proxy_addre"
\verb"ss" & Used to supply an alternative
endpoint in locally created object
references. This is intended for servers that export IORs for access
from outside a firewall.  The general form of the value is {\tt
  <protocol>://<address>}. The protocol name in the value must match
the protocol(s) used by the server. For example: {\tt
  iiop://myhost:1234}. The given address is inserted into every IOR
that the local ORB produces, without any check whether the address is
valid, except that the protocol must be supported by the ORB, and the
address must be parsable for that protocol. This property supercedes
jacorb.ior\_proxy\_host and jacorb.ior\_proxy\_port.
& string & unset \\
\hline
\verb"jacorb.ior_proxy_host" & The properties jacorb.ior\_proxy\_host and
jacorb.ior\_proxy\_port have been superceded by
jacorb.ior\_proxy\_address (see above), which is a
protocol-independent way of specifying endpoint addresses.  The
host/port properties are still recognized, but if
jacorb.ior\_proxy\_address is specified, it overrides these properties.
& node & unset \\
\hline
\verb"jacorb.ior_proxy_port" & See jacorb.ior\_proxy\_host and
jacorb.ior\_proxy\_address above &
port & unset \\
\hline
\verb"OAAddress" & Used to supply an explicit listener protocol and
address for servers. The general form of the value is
{\tt <protocol>://<address>}. The protocol name must match the
protocol(s) used by the server. For example: {\tt
  iiop://myhost:1234}. This property supercedes OAIAddr and OAPort.
& string & unset \\
\hline
\verb"OAIAddr" & The Object Adapter Internet Address: IP address on
multi-homed host (this gets encoded in object references). NOTE:
Addresses like 127.0.0.X will only be accessible from the same
machine! (This property is ignored if OAAddress is set.) & node & unset \\
\hline
\verb"OAPort" & See OAIAddr above (ignored if OAAddress is set) & port & unset \\
\hline
\verb"org.omg.PortableInterc"
\verb"eptor.ORBInitializerCl"
\verb"ass.standard_init" & Standard portable interceptor. DO NOT
REMOVE. & class &  \\
\hline
\verb"jacorb.net.socket_fact"
\verb"ory" & Sets or defines the socket factory that must implement
the operations defined in the org.jacorb.orb.factory.SocketFactory
interface. & class & \\
\hline
\verb"jacorb.net.server_sock"
\verb"et_factory" & Sets or defines the socket factory that must
implement the operations defined in the
org.jacorb.orb.factory.ServerSocketFactory interface. & class & \\
\hline
\verb"jacorb.net.socket_fact"
\verb"ory.port.min" & Sets the minimum port number that can be used
for an additional supported socket factory. This property is used in
conjunction with the jacorb.net.socket\_factory.port.max
property. These properties enable the factory to traverse firewalls
through a fixed port range  & integer & unset (disabled) \\
\hline
\verb"jacorb.net.socket_fact"
\verb"ory.port.max" & Sets the maximum port number that can be used
for the additional supported socket factory. Refer to
jacorb.net.socket\_factory.port.min above & integer & disabled\\
\hline

\end{longtable}
\end{small}


\begin{small}
\begin{longtable}{|p{5cm}|p{7.5cm}|p{1.5cm}|p{1.5cm}|}
\caption{Logging Configuration}\\
\hline
~ \hfill \textbf {Property} \hfill ~ & ~ \hfill \textbf {Description}
\hfill ~ & ~ \hfill \textbf {Type} \hfill ~ & ~ \hfill
\textbf{Default} ~ \endhead
\hline
\verb"jacorb.orb.print_versi"
\verb"on" & If enabled, the ORB's version number is printed whenever
the ORB is initialized. & boolean & on \\
\hline
\verb"jacorb.log.logger" & Name of the logger factory class, can be
used & class & {\tiny \verb"org.jacorb.util" }\\
\verb"LogFactory" & to plug in different log implementationas &  & {\tiny \verb"LogKitLoggerFactory" }\\
\hline
\verb"jacorb.log.default."
\verb"verbosity" & Log levels: 0 = fatal errors, 1 =
error, 2 = warning, 3 = info, 4 = debug & integer & 0 \\
\hline
\verb"jacorb.logfile" & Output destination for diagnostic log file. If
not set, diagnostics are sent to standard error.& filename & unset \\
\hline
\verb"jacorb.logfile.append" & Whether to append to
existing log file or overwrite (if file logging) & boolean & off \\
\hline
\verb"jacorb.logfile.maxLogS"
\verb"ize" & If appending to a file sets the size in kilobytes at
which the file is rolled over & integer & 0 \\
\hline
\verb"jacorb.debug.dump_outg"
\verb"oing_messages" & Hex dump outgoing messages & boolean & off \\
\hline
\verb"jacorb.debug.dump_inco"
\verb"ming_messages" & Hex dump incoming messages & boolean & off \\
\hline
\end{longtable}
\end{small}


\begin{small}
\begin{longtable}{|p{5cm}|p{9cm}|p{2cm}|}
\caption{Name service Configuration}\\
\hline
~ \hfill \textbf {Property} \hfill ~ & ~ \hfill \textbf {Description} \hfill ~ & ~ \hfill \textbf {Type} \hfill ~ \endhead
\hline

\verb"jacorb.naming.log." & The log level for the name & \\
\verb"verbosity" & service. Defaults to jacorb.log.default.verbosity & 0-4  \\
\hline
\verb"jacorb.naming.purge" & Whether non-active references are purged from name service
when list operation is invoked. Default is off & on or off \\
\hline
\verb"jacorb.naming.noping" & Whether resolve should return references without trying to
ping them to see if they're still alive first. Default is ping (off) &
on or off\\
\hline
\verb"jacorb.naming." & The file where the name server & string\\
\verb"ior_filename" &  drops its IOR (default unset) &   \\

\hline
\end{longtable}
\end{small}


\begin{small}
\begin{longtable}{|p{5cm}|p{9cm}|p{2cm}|}
\caption{POA Configuration}\\
\hline
~ \hfill \textbf {Property} \hfill ~ & ~ \hfill \textbf {Description} \hfill ~ & ~ \hfill \textbf {Type} \hfill ~ \endhead
\hline
\verb"jacorb.poa.monitoring" & Displays a GUI monitoring tool for servers. Default is off. & boolean \\
\hline
\verb"jacorb.poa.thread_pool"
\verb"_max" & Maximum thread pool configuration for request processing & integer \\
\hline
\verb"jacorb.poa.thread_pool"
\verb"_min" & Minimum thread pool configuration for request processing & integer \\
\hline
\verb"jacorb.poa.thread_prio"
\verb"rity" & If set, request processing threads in the POA will run at this priority. If not set or invalid, MAX\_PRIORITY will be used. Not set by default. & integer \\
\hline
\verb"jacorb.poa.queue_wait" & Specifies whether the POA should block
when the request queue is full (On), or throw TRANSIENT exceptions
(Off). Default is Off. & boolean\\
\hline
\verb"jacorb.poa.queue_max" & The maximum length of the request
queue.  If this length has been reached, and further requests arrive,
jacorb.poa.queue\_wait specifies what to do. Default is 100. & integer \\
\hline
\verb"jacorb.poa.queue_min" & If jacorb.poa.queue\_wait is On, and the
request queue gets full, then the POA blocks until the queue contains
no more than queue\_min requests. Default is 10. & integer \\
\hline

\end{longtable}
\end{small}


\begin{small}
\begin{longtable}{|p{5cm}|p{9cm}|p{2cm}|}
\caption{Implementation Repository Configuration}\\
\hline
~ \hfill \textbf {Property} \hfill ~ & ~ \hfill \textbf {Description} \hfill ~ & ~ \hfill \textbf {Type} \hfill ~ \endhead
\hline
\verb"jacorb.use_imr" & Switch on to contact the Implementation Repository (IR) on every server start-up. Default is off. & boolean \\
\hline
\verb"jacorb.use_imr_endpoin"
\verb"t" & Switch off to prevent writing the IMR address into server IORs. This property is ignored if jacorb.use\_imr = off. Default is off. & boolean \\
\hline
\verb"jacorb.imr.allow_auto_"
\verb"register" & If set to on servers that don't already have an entry on their first call to the IR, will get automatically registered. Otherwise, an UnknownServer exception is thrown. Default is off. & boolean \\
\hline
\verb"jacorb.imr.check_objec"
\verb"t_liveness" & If set on the IR will try to ping every object reference that it is going to return. If the reference is not alive, then TRANSIENT is thrown. Default is off. & boolean \\
\hline
\verb"ORBInitRef.Implementat"
\verb"ionRepository" & The initial reference for the IR. & URL \\
\hline
\verb"jacorb.imr.table_file" & File in which the IR stores data. & file \\
\hline
\verb"jacorb.imr.backup_file" & Backup data file for the IR. & file \\
\hline
\verb"jacorb.imr.ior_file" & File to which the IR writes its IOR. This is usually referred to by the initial reference for the IR (configured above).  & file \\
\hline
\verb"jacorb.imr.timeout" & Time in milliseconds that the implementation will wait for a started server to register. After this timeout is exceeded the IR assumes the server has failed to start. Default is 12000 (2 minutes). & millisec. \\
\hline
\verb"jacorb.imr.no_of_poas" & Initial number of POAs that can be registered with the IR. This is an optimization used to size internal data structures. This value can be exceeded. Default is 100. & integer \\
\hline
\verb"jacorb.imr.no_of_serve"
\verb"rs" & Initial number of servers that can be registered with the IR. This is an optimization used to size internal data structures. This value can be exceeded. Default is 5. & integer \\
\hline
\verb"jacorb.imr.port_number" & Starts the IMR on a fixed port (equivalent to the -p option). & integer \\
\hline
\verb"jacorb.imr.connection_"
\verb"timeout" & Time in milliseconds that the IR waits until a connection from an application client is terminated. Default is 2000. & millisec. \\
\hline
\verb"jacorb.implname" & The implementation name for persistent servers. See \ref{implname}. & name \\
\hline
\verb"jacorb.java_exec" & Command used by the IR to start servers. & command \\
\hline

\end{longtable}
\end{small}


\begin{small}
\begin{longtable}{|p{5cm}|p{9cm}|p{2cm}|}
\caption{Security Configuration}\\
\hline
~ \hfill \textbf {Property} \hfill ~ & ~ \hfill \textbf {Description} \hfill ~ & ~ \hfill \textbf {Type} \hfill ~ \endhead
\hline
\verb"OASSLPort" & The port number used by SSL, will be dynamically assigned by default. & port \\
\hline
\verb"org.omg.PortableInterc"
\verb"eptor.ORBInitializerCl"
\verb"ass.ForwardInit" & Portable interceptor required to support SSL. Not set by default. & class \\
\hline
\verb"jacorb.security.access"
\verb"_decision" & The qualified classname of access decision object. & class \\
\hline
\verb"jacorb.security.princi"
\verb"pal_authenticator" & A list of qualified classnames of principle authenticator objects, separated by commas (no whitespaces.). The first entry (that can be successfully created) will be available through the principal\_authenticator property. & class \\
\hline
\verb"jacorb.ssl.socket_fact"
\verb"ory" & The qualified classname of the SSL socket factory class. & class \\
\hline
\verb"jacorb.ssl.server_sock"
\verb"et_factory" & The qualified classname of the SSL server socket factory class. & class \\
\hline
\verb"jacorb.security.suppor"
\verb"t_ssl" & Whether SSL security is supported. Default is off. & boolean \\
\hline
\verb"jacorb.security.ssl.cl"
\verb"ient.supported_options" & SSL client supported options - IIOP/SSL parameters (numbers are hex values, without the leading 0x): NoProtection = 1, EstablishTrustInClient = 40, EstablishTrustInTarget = 20, mutual authentication = 60. Default is 0. Please see the programming guide for more explanation. & integer \\
\hline
\verb"jacorb.security.ssl.cl"
\verb"ient.required_options" & SSL client required options (See IIOP/SSL parameters above). Default is 0. & integer \\
\hline
\verb"jacorb.security.ssl.se"
\verb"rver.supported_options" & SSL server supported options (See IIOP/SSL parameters above). Default is 0. & integer \\
\hline
\verb"jacorb.security.ssl.se"
\verb"rver.required_options" & SSL server required options (See IIOP/SSL parameters above). Default is 0. & integer \\
\hline
\verb"jacorb.security.ssl.co"
\verb"rbaloc_ssliop.supporte"
\verb"d_options" & Used in conjunction with jacorb.security.ssl.corbaloc\_ssliop.required\_options. If these properties are set, then two values will be placed in the IOR, "corbaloc:ssliopÂ and "ssliopÂ. If not set, only EstablishTrustInTarget is used for both supported and required options. & integer \\
\hline
\verb"jacorb.security.ssl.co"
\verb"rbaloc_ssliop.required"
\verb"_options" &  Default is 0. & integer \\
\hline
\verb"jacorb.security.ssl.al"
\verb"ways_open_unsecured_en"
\verb"dpoint" &  Default is FALSE. The secure interoperabilty spec states that targets that require SSL shall not open (or publicise in their IORs) an unsecured listen port. Some ORBs (we're looking at you, MICO) apparently don't like this. Setting this switch to TRUE will override the correct behaviour for interoperability. Attempts to access the unsecured port should be met with a NO\_PERMISSION exception. & boolean \\
\hline
\verb"jacorb.security.keysto"
\verb"re" & The name and location of the keystore. This may be absolute or relative to the home directory. NOTE (for Sun JSSE users): The javax.net.ssl.trustStore [Password] properties doesn't seem to take effect, so you may want to add trusted certificates to normal keystores. In this case, please set the property jacorb.security.jsse. trustees\_from\_ks to on, so trusted certificates are taken from the keystore instead of a dedicated truststore.  & file \\
\hline
\verb"jacorb.security.keysto"
\verb"re_password" & The keystore password. & string \\
\hline
\verb"jacorb.security.truste"
\verb"es" & Files with public key certificates of trusted Certificate Authorities (CA). WARNING: If no CA certificates are present, the IAIK chain verifier will accept ALL otherwise valid chains. & file \\
\hline
\verb"jacorb.security.defaul"
\verb"t_user" & The name of the default key alias to look up in the keystore. & name \\
\hline
\verb"jacorb.security.defaul"
\verb"t_password" & The name of the default key alias to look up in the keystore. & string \\
\hline
\verb"jacorb.security.iaik_d"
\verb"ebug" & Sets IAIKS SSL classes to print debug output to standard output. Default is off. & boolean \\
\hline
\verb"jacorb.security.jsse.t"
\verb"rustees_from_ks" & Sun JSSE specific settings: Use the keystore to take trusted certificates from. Default is off. & boolean \\
\hline
\verb"jacorb.security.ssl.se"
\verb"rver.cipher_suites" & A comma-separated list of cipher suite names which must NOT contain whitespaces. See the JSSE documents on how to obtain the correct cipher suite strings. & string \\
\hline
\verb"jacorb.security.ssl.cl"
\verb"ient.cipher_suites" & See jacorb.security.ssl.server.cipher\_suites above. & string \\
\hline
\end{longtable}
\end{small}

\subsection{JacORB Implname and CORBA Objects}
\label{implname}
A JacORB object key consists of {\tt <impl name>/<poa name>/<object oid>}. The lifespan of CORBA objects are defined by the POA policy LifespanPolicyValue.

Transient objects are those whose lifespans are bounded by the process in which they were created. Once a transient object has been destroyed any clients still holding references to those objects should receive a OBJECT\_NOT\_EXIST. This applies even if the transient object is recreated as it is a new object reference. To achieve this JacORB replaces the implname portion of the key with transient data.

Persistent objects are those that may live beyond the lifetime of the process that created them. The implname property should be configured in this case. It should be set to a unique name to to form part of the object identity. If it is not set, an exception will be thrown. This property may be configured in the jacorb.properties (where an example shows it set to StandardImplName) or in the code of the server e.g.
\small{
\begin{verbatim}
    /* create and set properties */
    java.util.Properties props = new java.util.Properties();
    props.setProperty("jacorb.use_imr","on");
    props.setProperty("jacorb.implname","MyName");

    /* init ORB  */
    orb = org.omg.CORBA.ORB.init(args, props);
\end{verbatim}
}

The implname property allows a program to run with a different implementation name so that it will not accept references created by another persistent POA with the same POA name. A common problem is where the developer has two persistent servers running with the same implname and POA names when one tries to contact the other. Rather than calling server x, server y performs local call. This is because there is no way of distinguishing the two servers; the developer should have used different implnames (e.g. UUIDs).

As it is not possible to construct a transient object with a readable key unlike a persistent object where the developer may configure implname, POA name and object key as they wish, some developers may find it useful to use the objectKeyMap facility within JacORB to refer to their transient objects.

This property provides more readable corbaloc URLs by mapping the actual object key to an arbitrary string. The mapping below would permit clients of a name service to access it using corbaloc::ipaddress:portnum/NameService. The property also accepts the following mappings:
\begin{itemize}
\item IOR, resource, jndi, URL (e.g. file, http)
\end{itemize}
Note that {\tt jacorb.orb.objectKeyMap.name} is configurable both through the jacorb.properties file and through the proprietary function

{\tt ORB::addObjectKey(String name, String)}

Example usage

{\tt jacorb.orb.objectKeyMap.NameService=file:///home/rnc/NameSingleton.ior}



%%% Local Variables:
%%% mode: latex
%%% TeX-master: "../ProgrammingGuide"
%%% End:
