Admin

Administrator 3.1
Guide

© 1997-1999 ObjectSpace, Inc. All rights reserved.
ObjectSpace, Inc., has used its best efforts in preparing this book. These efforts
include the development, research, and testing of the theories and programs to
determine their effectiveness. ObjectSpace, Inc., makes no warranties of any kind,
expressed or implied, with regard to these programs or the documentation contained in
this book. ObjectSpace, Inc., shall not be liable in any event for incidental or
consequential damages in connection with, or arising from, the furnishing,
performance, or use of these programs.
Voyager, Space, and Dynamic Aggregation are trademarks of ObjectSpace, Inc.
Java is a trademark of Sun Microsystems.
All other brand or product names are trademarks or registered trademarks of their
respective holders.
RESTRICTED RIGHTS LEGEND
Voyager ORB Professional, Voyager Security and Voyager Transactions are
furnished under a license and may not be used, copied, disclosed, and/or
distributed except in accordance with the terms of said license. No classes,
hierarchies, methods, binaries, or code may be copied for implementation in
other systems.
This document and all online system documentation are copyrighted 1997-1999 by
ObjectSpace, Inc. All rights reserved. No portion of this document may be copied,
photocopied, reproduced, transcribed, translated, or reduced into any language, in any
form or by any means, without the prior written consent of ObjectSpace, Inc.
This document is subject to change without notice.
Software Version

3.0

Second Edition
Printed in the United States of America

Contents
1

Overview 1
Configuring and Managing a Distributed System 2

2

Voyager Directory Server 3
Using an LDAP Server 4
Starting a Voyager Directory Server 8
Communicating with a Voyager Directory Server 9

3

Voyager Management Console 11
Understanding the Structure of the VMC 12
Accessing an LDAP Directory Server 13
Starting VMC 13
Initializing the Voyager Directory Server 15
Installing Services 15
Creating Server Profiles 16
Creating Clusters 16

4

Voyager Servers 21
Configuring Voyager Servers 22
Defining System Properties 24
Defining CORBA-to-Java Mappings 25
Startup Using Voyager Directory Server 26

Voyager Core Technology User Guide

iii

Running Directory Server and Voyager Server in the Same VM 27
Managing Running Voyager Servers 27
5

6

Transaction Service 45
Monitoring Transaction Statistics 46
Viewing the Transaction Log 47
Viewing Active Transactions 49
Viewing Transaction Errors 50
Configuring Transactions 51
Communicating with the Server 52

7

JDBC Service 53
Configuring Datasource Properties 54

8

iv

Security Service 31
Securing the VMC and Directory Server 32
Securing the VMC Using a Custom Policy Implementation 34
Securing Voyager Servers Using BasicPolicy 34
Managing the Access Control List 39

EJB Service 57
Monitoring EJB Container Statistics 58
Configuring the EJB Container 60
Configuring an EJB Service with an LDAP Directory Service 67
Monitoring a Component’s Statistics 69
Configuring a Component’s General Properties 70
Viewing a Component’s Transactional Properties 72
Setting a Component’s Security Properties 73
Setting a Component’s Environment Properties 75
Viewing a Method’s Transactional Properties 78
Setting a Method’s Security Properties 79

Voyager Configuration
and Management

1

Overview
This manual details Voyager’s configuration and management capabilities.
Several tools are used in deploying and maintaining a distributed system
using Voyager:








Voyager Directory Server–serves as a naming service, the central
repository for configuration information, and a record of servers that are
currently running.
Voyager Management Console–allows you to view and change
information within the directory, as well as communicate directly with
services running on remote Voyager servers.
Voyager Server–can be configured remotely from the Voyager Directory
Server. At startup, servers retrieve their configuration information from the
directory and allow management of their services through Management
Agents.

1

Configuring and Managing a
Distributed System
When implementing any distributed system, you need a way of remotely initializing and
keeping track of servers in the field. For example, you want to be able to set runtime
parameters for any server in your system without having to physically sit at the machine
in question. You will also want to be able to know, at any point in time, which servers
are running and what state those servers are in.
Voyager addresses these concerns with the following architecture:
A central Voyager Directory Server stores all server profile information. Server profiles
are entries in the Voyager Directory Server that describe the services a particular
Voyager server runs and their configuration. Server profiles are associated with actual
Voyager servers when those servers are brought online.
Management and administration tools discover from the Voyager Directory Server the
remote Voyager servers that are running along with their configuration. In addition,
services running on each Voyager server can expose special “management agent”
objects through which they can be observed and manipulated. Proxies to these
management agents are also registered in the Voyager Directory Server under each
server’s service profile so that tools such as the Voyager Management Console (VMC)
can interact with the service’s managed objects.
The VMC is a graphical tool for administering the directory and monitoring and
configuring servers and services. Using the VMC you can set up a directory server,
create new server profiles, edit configuration information, and interact with
management agents.
Voyager add-on services, such as Voyager Transactions, Voyager Security, and
Voyager Application Server, are all managed using the VMC. You can also create your
own services and management screens by extending the same frameworks upon which
Voyager’s add-ons are built.
When a directory server is initialized, if you have Voyager Security, Voyager
Transactions, or Voyager Application Server, the console automatically installs these
services in the directory server.

2

Chapter 1 • Overview

Voyager Directory Server

2

The Voyager Directory Server is a central repository for configuration
information. The Voyager Directory Server uses Voyager’s implementation
of JNDI and its Persistent Directory feature to store information.
In this chapter, you will learn to:








use an LDAP server
start a Voyager Directory Server
communicate with a Voyager Directory Server

Note: The content and structure of a Voyager Directory Server are described
in more detail in the Voyager ORB Developer Guide.

3

Using an LDAP Server
To use an LDAP server, you must:








update the LDAP schema
create the Voyager directory tree
set up JNDI

Updating the LDAP Schema
Voyager stores information in a directory server as Java objects. The Internet
Engineering Task Force’s (IETF) draft file “draft-ryan-java-schema-02.txt,” distributed
as a text file on the Voyager 3.1 CD, defines an LDAP schema for Java objects. To use
Voyager with an LDAP server that uses schema checking, you must add this schema for
Java objects to the server. Consult your directory server documentation for instructions
regarding schema additions.

Creating the Voyager Directory Tree
Voyager assumes that the root directory object is a Java container as defined by the
Internet draft “draft-ryan-java-schema-02.txt”. (See the text file that was distributed
with your Voyager CD.) You must create a directory tree with a Java container object as
its root. The distinguished name for this Java container object must be the cn attribute.
Here is an example of a Voyager root directory object:
dn: cn=VoyagerDirectory
cn: VoyagerDirectory
objectclass: top
objectclass: javaContainer

Given the above root directory object, Voyager will require the following URL to access
the directory. This URL specifies a directory server on a machine called dallas that is
listening on port 389. Consult your directory server documentation for instructions on
creating directory root objects.:
//dallas:389/VoyagerDirectory

4

Chapter 2 • Voyager Directory Server

JNDI Configuration
Voyager uses Java Naming and Directory Interface (JNDI) to access LDAP directory
servers. JNDI is a Java API that provides a standard interface for accessing different
naming and directory service implementations.

Setup
For each naming and directory service implementation, JNDI requires a specific service
provider. The service provider contains the Java classes necessary to access a specific
naming or directory implementation. To use Voyager with LDAP directory servers,
either an implementation-specific LDAP service provider or Sun’s LDAP service
provider is required.
Consult your directory server documentation for instructions regarding installation of
the LDAP service provider, or consult Sun’s web site to obtain Sun’s LDAP provider.
Once the service provider is installed, verify that the proper Java classes are accessible
from the classpath environment variable. Also, note the name of the initial context
factory class. The name of this class is provider-specific and will be needed later to
properly configure Voyager to use the LDAP directory server. For Sun, the class name
is com.sun.jndi.ldap.LdapCtxFactory.

Initial Context Factory
When creating an initial context to access a specific naming or directory
implementation, JNDI uses an initial context factory provided by the JNDI service
provider. Voyager must always be configured to use its own initial context factory to
access naming and directory implementations through JNDI. When using Voyager with
a naming or directory implementation other than Voyager Directory Server, Voyager’s
initial context factory delegates the creation of initial contexts to an initial context
factory from an alternate service provider, such as Sun’s LDAP provider. If an alternate
service provider is used, Voyager will add Voyager-specific functionality to the initial
context returned from the alternate service provider’s initial context factory before
returning it to the client.
When used with LDAP, Voyager will use Sun’s LDAP service provider by default. An
alternate LDAP provider can also be used. The following section describes the system
properties used to configure Voyager for use with LDAP and how to specify an alternate
LDAP provider.

Voyager Adminstrator Guide

5

System Properties
JNDI uses system properties to communicate certain information from the JNDI client
to the JNDI service provider. Voyager also uses system properties to configure Voyager
for use with LDAP directory implementations. These system properties are specified in
a Java properties file that is read by the Voyager Management Console on startup.
The name of the system property Voyager uses to determine the directory server
implementation is objectspace.directory.server.implementation. For LDAP directory servers,
the value of this property must be ldap. If this property is not set, Voyager Directory
Server will be used. If LDAP is specified, Voyager will, by default, delegate initial
context requests to Sun’s LDAP initial context factory. When using a different LDAP
service provider, set the objectspace.alternate.context.factory system property. The value of
this property must be the initial context factory of the alternate service provider. For
example:
java.naming.factory.initial=com.objectspace.voyager.jndi.spi.VoyagerContextFactory
objectspace.directory.server.implementation=ldap
objectspace.alternate.context.factory=com.company.LDAPInitialContextFactory

In the example, com.company.LDAPInitialContextFactory is the initial context factory
delivered with the alternate LDAP service provider.
The following table summarizes the most common set of properties required by
Voyager to access LDAP directory servers using JNDI.
Property Name
objectspace.directory.server.implementation

6

Property Description
This property is required when using
Voyager with naming or directory
implementations other than Voyager
Directory Server unless the provider URL
contains the LDAP protocol. See the
following section for more information
about the URL format. To use Voyager with
LDAP the value must be ldap.

Chapter 2 • Voyager Directory Server

Property Name

Property Description

objectspace.alternate.factory.initial

The class name of the alternate initial
context factory to be used by Voyager to
access the LDAP server. This class is
included in the LDAP service provider. This
property is only required for LDAP service
providers other than Sun’s.

java.naming.factory.initial

The value of this property must always be
com.objectspace.voyager.jndi.spi.VoyagerContext
Factory.

java.naming.security.authentication

Indicates the level of security authentication
supported by the directory server client. The
value for this property will always be simple
for this version of Voyager. This property is
required.

java.naming.security.principal

Identity or principal used by the
authentication scheme. This will be a simple
text-string user name for this version of
Voyager.

java.naming.security.credential

Principal’s credential for the authentication
scheme. This will be a simple text-string
password for this version of Voyager.

The specific LDAP application or the LDAP service provider may require other system
properties. Consult your directory server and service provider documentation for
information regarding environment properties.

LDAP Security
Currently Voyager only supports simple text string user names and passwords for
accessing LDAP directories.

Voyager Adminstrator Guide

7

Starting a Voyager Directory Server
Initiate a Voyager Directory Server by starting Voyager from the command line using
the -j and -f options.
voyager 8000 -j dir -f 8000.db

Required pieces of information follows:








a port to listen on
-j and a name to which to bind the directory
-f and the file to write items that are bound into the directory

The URL of this directory is now //dallas:8000/dir, where dallas is the hostname of the
system on which the directory was started.

Starting a Voyager Directory Server with LDAP
To associate a Voyager server with a server profile created by the VMC in an LDAP
server, start the Voyager server with the -d and -p options. For example, to use a server
profile called Servers/server1 in a Voyager directory tree called VoyagerConfig on a
machine called dallas that is listening on port 389, use the following command:
voyager -d //dallas:389/VoyagerConfig/Servers/server1 -p ldap.properties

The -p option requires a file containing system properties. The properties file should
contain all of the properties described in “System Properties” on page 6, as well as any
properties that are required by the LDAP server and the JNDI service provider being
used. An example properties file with settings for the above example follows:
java.naming.factory.initial=com.objectspace.voyager.jndi.spi.VoyagerContextFactory
java.naming.security.authentication=simple
java.naming.security.principal=directoryUser
java.naming.security.credential=userPassword
objectspace.directory.server.implementation=ldap

Note: The principal and credential property values should represent a user in the LDAP
directory with all access permission to the Voyager directory tree.

8

Chapter 2 • Voyager Directory Server

Communicating with a Voyager
Directory Server
Any JNDI client can communicate with a Voyager Directory Server. When a JNDI
client is communicating with a Voyager Directory Server, the server needs to be started
with the -r parameter See the Voyager ORB Developer Guide for information on
obtaining an initial context for a given directory.
The preferred method of communicating with a Voyager Directory Server, within the
context of configuration and management, is via the Voyager Management Console or
VMC.

Voyager Adminstrator Guide

9

10

Chapter 2 • Voyager Directory Server

Voyager Management Console

3

The Voyager Management Console (VMC) communicates with a Voyager
Directory Server and manages its contents. It is also capable of
communicating directly with services on remote Voyager servers.
In this chapter, you will learn to:
















understand the structure of the VMC
access an LDAP directory server
start the VMC
initialize the Voyager Directory Server
install services
create server profiles
create clusters

11

Understanding the Structure of the
VMC
The main window of the VMC consists of three sections. On the left side is the tree
view. It represents the content of the Voyager Directory Server. When a particular node
in the tree is selected, tabs for objects contained in that node are on the right. The status
window at the bottom relays status information and error messages.

Tree View

12

Tabs Related to Selected Node

Status Window

Chapter 3 • Voyager Management Console

Accessing an LDAP Directory Server
The VMC uses a Java properties file to load the system properties required to access an
LDAP directory server. The filename is specified on the command line when starting the
VMC. For example, to start the console with a file named ldap.properties, use the
following command:
console ldap.properties

The following is a properties file example using Sun’s service provider:
java.naming.factory.initial=com.objectspace.voyager.jndi.spi.VoyagerContextFactory
java.naming.security.authentication=simple
objectspace.directory.server.implementation=ldap

By default, VoyagerContextFactory delegates to Sun’s LDAP initial context factory.
Notice that the java.naming.security.principal and java.naming.security.credential entries are not
included. The VMC will add the principal and credential from the login dialog to the
system properties.
The directory URL entered in the VMC login dialog must be the URL of the LDAP
directory server, without the protocol, plus the name of the Voyager directory tree. For
example, to access an LDAP directory tree named Voyager on a directory server on a
machine called dallas that is listening on port 389, use the following URL:
//dallas:389/Voyager

Note: Users of the VMC must be given all access permission to the Voyager directory
tree.

Starting VMC
Run the console utility to start the VMC. On startup, the VMC presents a dialog that
prompts you for a user name, password, and directory URL.

Voyager Adminstrator Guide

13

If the directory server is not secured, leave the name and password fields blank. If you
have the security service installed, see the "Security Service" chapter for more
information. In the URL field, specify the location of a running Voyager Directory
Server. For example, start a directory server on a machine called dallas with the
following command:
voyager //dallas:8000 -j dir -f 8000.db

Then fill in the following as the directory URL:
//dallas:8000/dir

14

Chapter 3 • Voyager Management Console

Initializing the Voyager Directory
Server
If the Voyager Directory Server has never been visited by a VMC before, the VMC
informs you that the Voyager Directory Server is not initialized. Voyager presents a
dialog box asking whether you want to initialize the directory. This process creates a
default server profile template in the Voyager Directory Server from which server
profiles are built.

Installing Services
Any time after the Voyager Directory Server is initialized, you may add new services to
the server profile template by selecting Install service… from the File menu. This brings
up a file chooser dialog that is used to select either the jar file in which the desired
service was distributed or a serialized configuration object, which is a file with the
extension SER, distributed separately from the jar file. Information specific to that
service is then added to the Voyager Directory Server’s server profile template.

Voyager Adminstrator Guide

15

Creating Server Profiles
Server profiles specify the runtime properties of servers in your system. To create a new
server profile, select New server profile… from the File menu. A dialog opens that
prompts you for a URL and allows you to select desired services from a list of services
that have been installed (see the "Installing Services" section on page 15).

The URL field is interpreted as relative to the root of the Voyager Directory Server. For
example, if you specify Servers/Test in the URL field, the server profile is at URL
//dallas:8000/dir/Servers/Test, where dallas is the machine name of the directory server, 8000
is its port, and dir is the name to which the directory is bound.
Server profile URLs may be specified arbitrarily. There is no predefined directory
structure for server profiles.

Creating Clusters
The Voyager Management Console makes it easy to create and administer a cluster of
servers that all share a set of configuration information.You can create logical clusters
to manage multiple servers. A logical cluster contains settings common to multiple
16

Chapter 3 • Voyager Management Console

servers. Once a cluster has been created, any server profiles created under this cluster or
moved to this cluster will acquire the settings for the cluster. Some settings may be
modified only for the entire cluster, and others may be modified only within a server
profile.

How to Create a Cluster
Step 1. From the File menu, select New Server Cluster. The new server cluster dialog
box opens.
.

Step 2. Enter the name for the cluster you are creating, and select the services to be
installed on that cluster.
Step 3.

Click OK. A cluster icon will appear in the tree window.

Step 4. Configure the sharable information for that cluster by selecting the cluster icon
in the tree window.
Step 5. Configure the sharable service information for the installed services by
selecting the service nodes directly under the cluster node in the tree window.

Voyager Adminstrator Guide

17

Adding Servers to a Cluster
Once you’ve created a server cluster you can add servers that shared the configuration
information for that cluster.
Step 1. To add a new server profile to a cluster, select the New Server Profile from the
File menu. The new server profile dialog box will open, displaying a drop-down list of
the available clusters.

Step 2. In the available cluster list, select the cluster to which you want to add the new
server. The list of selectable services is disabled when you select one of the available
clusters. Since each server placed in a cluster is virtually identical, the only services
installed for each server will be the services installed on that cluster.

18

Chapter 3 • Voyager Management Console

Step 3. Click OK. The new server profile will appear as a child node of the cluster to
which it was added.

Moving a Server from a Cluster
Step 1. To move a server to a different cluster or make a server a non-clustered server,
select the server node in the tree window.
Step 2. In the Create in Cluster list, select the new cluster to which you wish to move
the server. The server profile will immediately be moved to its new cluster. If you select
“No Cluster”, it will no longer be a part of any cluster.
Step 3. Once you move a server to a new cluster, that server begins to share the
sharable configuration information of its new cluster. If you select “No Cluster” and
move the server profile out of all of the available clusters, the information that the profile
shared with its previous cluster will remain with the server, but it will no longer be shared
with that cluster.

Voyager Adminstrator Guide

19

For more information on the administering either the individual servers or any of the
services installed on a cluster, see the sections on “Voyager Servers” and “Voyager
Services: in the Voyager Administrator Guide.
Note: When a administering either a cluster or a server in a cluster, only certain
information may be modified. Shared information may only be modified on the
cluster node (or cluster services), and the server-specific information may only
be modified on the server node.

Starting a Voyager Server in a Cluster
As specified in the section on starting Voyager with a directory server, if you start the
directory server containing the configuration information by:
voyager 8000 –f dir.db dir

or
voyager 8000 –j dir –f dir.db

and a server is created with the name Server, the following command starts the server
with the configuration information stored in the directory server:
voyager –d //dallas:8000/dir/Server

If that server profile is stored as a part of a cluster named Cluster, the startup command
becomes:
voyager –d //dallas:8000/dir/Cluster/Server

If the server profile is moved back out of the cluster, the startup command returns to:
voyager –d //dallas:8000/dir/Server

20

Chapter 3 • Voyager Management Console

4

Voyager Servers
With the VMC, you can view and change the configuration options and
runtime setup of Voyager servers. Additionally, remote Voyager servers can
now discover configuration information from the directory during startup.
In this chapter, you will learn to:














configure Voyager servers
define system properties
define CORBA-to-Java mappings
start Voyager servers
run directory server and Voyager server in the same VM
manage Voyager servers

21

Configuring Voyager Servers
You can configure a number of aspects of a Voyager server within the server profile.
The Server Configuration tab offers the following:


















22

Startup URL – the port on which the Voyager server should listen for incoming
connections.
Startup application – the class name and arguments for an application class to be
executed on startup. The main method of the class is called with the remaining Strings
passed in as arguments.
Maximum number of idle threads – an integer that tells the ThreadManager an upper
bound for the size of the idle thread pool.
Voyager security manager – a flag that toggles whether a VoyagerSecurityManager is
installed on startup.
Enable resource serving – a flag that enables the HTTP resource server.
Enable resource loading – a flag that enables Voyager’s class loading mechanisms.
If this is disabled, dynamic proxy generation does not occur.
Resource URLs – a list of addresses of HTTP servers that this Voyager server should
consult for resources.
Other resource loaders – a list of class names used as alternate resource loaders
within this Voyager server.

Chapter 4 • Voyager Servers

Note: Changes do not take effect while a Voyager server associated with this profile is
running. Also, updating the configuration is not transactional, so there is no
locking against multiple VMCs editing the same configuration.

Voyager Adminstrator Guide

23

Defining System Properties
System properties for the server may also be set in the profile. The Server Properties tab
allows editing of existing properties and the addition of new ones. Properties are added
to the server after the virtual machine starts, but before Voyager finishes starting up.

24

Chapter 4 • Voyager Servers

Defining CORBA-to-Java Mappings
You can override the default CORBA mapping rules on the CORBA<->Java Mappings
panel. These mappings will be considered in addition to any that are specified on the
command line.
To add a mapping, press the add button and fill in the name of the IDL entity and the
Java class name you want it mapped to.

See the CORBA section of the Voyager ORB Developer Guide for more information.

Voyager Adminstrator Guide

25

Startup Using Voyager Directory
Server
To associate a Voyager server running on any computer on the network with a specific
entry in the Voyager Directory Server, run the voyager utility as follows:
voyager –d //dallas:8000/dir/Servers/Test

This example associates the Voyager server with an entry called Servers/Test in the
Voyager Directory Server running at //dallas:8000 whose directory is bound to the name
dir.
During startup, Voyager contacts the directory server and retrieves its server
configuration object, which contains all of the runtime configuration information for the
Voyager server itself. Voyager also iterates through the other entries in the specified
profile. It retrieves any configuration objects for services. When each service is started,
it is responsible for installing a Management Agent back into the server profile in the
Voyager Directory Server if necessary.
To associate a Voyager server with a server profile created using the Voyager
Management Console (VMC) that is stored in a Voyager Directory Server, run the
Voyager utility with the -d option. For example, if a server profile named servers/test was
created in a Voyager Directory Server running on a machine named dallas that is
listening on port 8000 use the following command:
voyager –d //dallas:8000/servers/test

If the Voyager Directory server is secured using BasicPolicy, then BasicPolicy must also be
used to secure the Voyager server being configured. In addition, a user name and
password must be specified to allow the Voyager server to connect to the Voyager
Directory Server. To specify the security policy implementation and the user name and
password, use the voyager utility -p option. The -p option loads system properties from a
file. The file name is specified on the command line. For example:
voyager –d //dallas:8000/servers/test –p properties.file

In the above example properties.file is the file name of a file containing the information
necessary to allow the Voyager server to access the Voyager Directory Server. An
example file follows:

26

Chapter 4 • Voyager Servers

objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy,props/security.server.properties
java.naming.security.principal=directoryAdmin
java.naming.security.credentials=directoryAdmin

In the above example, the property keys java.naming.security.principal and
java.naming.security.credentials are JNDI environment properties that the Voyager JNDI
service provider uses when connecting to the Voyager Directory Server. The
objectspace.security.policy.1 property key specifies the security policy implementation to
the Voyager Security Framework. The process of loading a security policy is described
in more detail in the Voyager Administration Guide and the Voyager Security Developer
Guide.

Running Directory Server and
Voyager Server in the Same VM
If you need to have the Voyager Directory Server and a regular Voyager server running
on the same VM, use the -j, -f and -d options together. For example:
voyager 8000 -j dir -f 8000.db -d 8000/dir/Servers/Test

This example assumes that there is already a file called 8000.db that is a valid Voyager
Directory Server database and contains a profile called Servers/Test.
Note: In this case only, when specifying the profile URL after the -d option, do not
include the machine name or IP address for the local host.

Managing Running Voyager Servers
To manage running Voyager servers, refer to the Voyager ORB Developer Guide.

Voyager Adminstrator Guide

27

28

Chapter 4 • Voyager Servers

Voyager Services

5

Security Service
With the features of Voyager Security, you can secure both Voyager servers
and the VMC.
In this chapter, you will learn to:










secure the VMC and Directory Server
secure the VMC using a custom policy implementation
secure Voyager servers using BasicPolicy
manage the Access Control List (ACL)

Note: The security service is only available in the Voyager Security and
Voyager Application Server products.

31

Securing the VMC and Directory
Server
Secure the Voyager Management Console and the Voyager Directory Server with the
following steps:
Step 1.

Start an unsecured Voyager Directory Server. For example:

voyager 8000 -j dir -f 8000.db

Step 2.

Start an unsecured Voyager Management Console.

Step 3. Install the security service. Select Install Service from the file menu of the
VMC, then choose the Security Service's jar file or serialized configuration object from
the resulting file dialog.
Step 4. Create or import a system user using the Voyager Management Console. Create
a user with the tools described in the "Managing the Access Control List" section on page
39. The user represents the system when it accesses the directory server. This user must
be granted directory permission. Adding permissions to users is described in the
"Managing the Access Control List" section. Optionally other users could be added at this
step, but the system user is required.
Step 5. Restart the Voyager Directory Server in a secured state. Stop the directory
server started in step 1. Restart it using the -p option. For example:
voyager 8000 -j dir -f 8000.db -p server.properties

The file specified with the -p option should contain the following text:
objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy, filename

filename is the name of the file with the security properties. For example:
objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy,security.properties

32

Chapter 5 • Security Service

This file must contain the following entries:
policy.server

Must be set to true.

directory.url

The URL of the directory server.

directory.username

Leave blank.

directory.password

Leave blank.

security.owner.username

Leave blank.

security.owner.password

Leave blank.

security.system.username

Set to the user name of the system user created in step
4.

security.system.password

Set to the password of the system user created in step
4.

An example using the directory server example follows:
policy.server=true
directory.url=//dallas:8000/dir
directory.username=
directory.password=
security.owner.username=
security.owner.password=
security.system.username=systemUser
security.system.password=systemUserPassword

Step 6. Restart the VMC in a secured state. Stop the management console started in
step 2. Restart a secured management console. To start a secured management console,
type console at the command line followed by a file name. For example:
console client.properties

The file client.properties should contain the following text:
objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy

After this setup process is completed, the VMC requires a user name and password to
log in. For users to login to the console, they must have directory permission. Any
Voyager server started using the voyager utility with the -d option will also require the
user name and password of a user with directory permission. To specify the user name
and password use the -p option of the voyager utility. The -p option requires a properties
file. The properties file should include the following:
Voyager Administrator Guide

33

objectspace.config.password=username
objectspace.config.username=password

where username is the user name of the user that exists in the ACL with directory
permission, and password is the password of this user.

Securing the VMC Using a Custom
Policy Implementation
Custom security policy implementations can also be used with the Voyager
Management Console. See the Voyager Security Developer Guide for information
regarding implementing a security policy.
To secure the Voyager Management Console with a custom policy implementation type
console at the command line followed by a file name. For example:
console custom.policy.properties

The file custom.policy.properties should contain the text “objectspace.security.policy.1=”
followed by the fully qualified class name of the custom policy implementation.

Securing Voyager Servers Using
BasicPolicy
The Voyager BasicPolicy security policy implementation is a security policy that helps
the development of secured applications and serves as a reference for domain-specific
policy development. Do not deploy production-quality applications with this
implementation.
BasicPolicy ensures that a user requesting a service from a Voyager server has permission
to use that service. BasicPolicy stores users and their access permissions in the Access
Control List (ACL). BasicPolicy obtains the ACL at startup from a Voyager Directory
Server. The Voyager Directory Server is specified by a URL read from a properties file

34

Chapter 5 • Security Service

loaded by the BasicPolicy during startup. BasicPolicy on a running server will be notified
by the VMC when changes are made to the ACL.
Note: BasicPolicy on a running server will not be notified of ACL changes if the VMC is
run in an unsecure state. The following section explains how to secure the VMC and
the Voyager Directory Server using BasicPolicy.
To secure a Voyager server, specify the security policy implementation during startup.
Voyager obtains the configuration information from a properties file. Use the -p option
when starting a Voyager server to specify the properties file. For example:
voyager -p server.properties 8000

To use BasicPolicy, the file specified with the -p option must contain the following text:
objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy, filename

filename is the name of the file with the security properties. For example:
objectspace.security.policy.1=com.objectspace.security.policy.BasicPolicy,security.properties

Alternatively, you can specify that BasicPolicy be the security policy implementation
using the VMC Server Properties tab that defines system properties for a server profile.
Use objectspace.security.policy.1 as the property key and
com.objectspace.security.policy.BasicPolicy, filename as the property value where filename is the
name of the file with the security properties as above.
The file can contain the following entries:
policy.server

Must be set to true or false. Set to true on a server. If true,
complete all subsequent fields.

directory.url

The URL of the directory server.

directory.username

The user name the BasicPolicy in the directory server will
use to access the directory server. This user should exist in
the ACL on the directory server and be granted
DirectoryPermission.

directory.password

The password of the user the BasicPolicy in the directory
server will use to access the directory server.

Voyager Administrator Guide

35

security.owner.username

The user name of the security owner. The security owner is
the user with permission to access certain security
functions on the server. These functions might include
setting the default principal. For a complete list of owner
permissions, see the Voyager Security Developer Guide.

security.owner.password

The password of the security owner.

security.system.usernam
e

The user name the system uses to perform secure system
actions.

security.system.password

The password the system uses to perform secure system
actions.

An example of a properties file for the BasicPolicy follows:
// if true, all subsequent fields must be filled in
policy.server=true
directory.url=7000/JNDI
directory.username=directoryAdmin
directory.password=directoryAdmin
security.owner.username=securityOwner
security.owner.password=securityOwner
security.system.username=systemPrincipal
security.system.password=systemPrincipal

Clients that use servers secured by the BasicPolicy must also specify BasicPolicy as their
security policy. The properties file is optional for the client and should only be used to
specify a security owner if needed. If a properties file is used by a client, policy.server
should equal false.
Note: Passwords are stored in clear text, so it is critical that you protect the properties
file from unauthorized access on the native platform.

Using Basic Policy with an LDAP Directory Server
To use Basic Policy with an LDAP directory server implementation, add the following
properties to the Basic Policy properties file:

36

Chapter 5 • Security Service

Property Key

Property Value

objectspace.directory.server.implementation

ldap

java.naming.factory.initial

com.objectspace.voyager.jndi.spi.VoyagerContext
Factory

java.naming.security.authentication

simple

Note: Voyager servers using BasicPolicy which read the ACL from an LDAP directory
server must be restarted for any changes to the ACL to take effect.
The following is an example of a Basic Policy properties file with the above properties
added. In this example, Sun’s LDAP service provider is used:
// if true, all subsequent fields must be filled in
policy.server=true
directory.url=//localhost:7000/ACLDirectory
directory.username=directoryAdmin
directory.password=directoryAdmin
security.owner.username=securityOwner
security.owner.password=securityOwner
security.system.username=systemPrincipal
security.system.password=systemPrincipal
objectspace.directory.server.implementation=ldap
java.naming.factory.initial=com.objectspace.voyager.spi.jndi.VoyagerContextFactory
java.naming.security.authentication=simple

Basic Policy uses the directory.username and the directory.password properties as the user
name and password to access the directory server. This user must have read and write
access to the Voyager directory tree. Also the directory.url entry is the URL used by the
Basic Policy to access the directory. In this example, //localhost:7000 is the URL to the
directory server, and the Voyager directory tree name is ACLDirectory.
To use an initial ContextFactory other than Sun’s, use the objectspace.alternate.factory.initial
property.

Voyager Administrator Guide

37

ACL Installer
Installer is a command line tool used to load a Basic Policy ACL into the directory server.
To use installer with an LDAP directory server, pass a properties file name as the second
parameter when invoking installer. For example:
aclinst //dallas:389/ACL simple.acl ldap.props

The above example specifies a directory server on a machine called dallas that is
listening on port 389. The Voyager directory tree name is ACL.
The properties file must contain the following properties:
Property Key

Property Value

objectspace.directory.server.implementation

ldap

java.naming.factory.initial

com.objectspace.voyager.jndi.spi.VoyagerContext
Factory

java.naming.security.authentication

simple

java.naming.security.principal

A simple text string user name that will be
used to log into the directory server.

java.naming.security.credential

A simple text string password that will be
used to log into the directory server.

The following is an example properties file:
java.naming.factory.initial=com.objectspace.voyager.jndi.spi.VoyagerContextFactory
java.naming.security.authentication=simple java.naming.security.principal=directoryUser
java.naming.security.credential=userPassword
objectspace.directory.server.implementation=ldap

The example properties file uses Sun’s service provider. The user represented by the
java.naming.security.principal and java.naming.security.credential entries must have read and
write access to the Voyager directory tree. To use an initial ContextFactory other than
Sun’s, use the objectspace.alternate.factory.initial property.

38

Chapter 5 • Security Service

Managing the Access Control List
The ACL is a list containing information about the users of the system. The ACL
contains the user name, password, and access permissions granted to the user.
After the security service is installed in the VMC, the Security node appears under the
VoyagerDirectory node in the tree view on the left side of the VMC main window. When
you select the Security node, the security management panels appear on the right with
tabs for managing permission types and managing the ACL.
Use the Manage ACL panel to add users, change passwords, and grant users access
permissions. Use the Manage Permission Types List panel to add new permission types.
Use the “Import” button to add users from a file.
Any changes including imports to the ACL are kept locally on the Voyager
Management Console client. Press the Accept button to commit changes to the directory
server. The accept function commits all changes, including changes to the permission
types. Press the Cancel button to reload the previous ACL from the directory server. The
cancel function rolls back all changes, including changes to the permission types.

Voyager Administrator Guide

39

Adding and Removing Users
Maintain users from the Manage ACL panel. Add and remove users and change
passwords from this panel.

Use the buttons below the “Users” list to add users, remove users, and update user
passwords.

Adding a User
Adding a user creates an entry in the ACL with the user name and password of the user.
Two users are equal when they have the same user name and password. Therefore a user
can have multiple passwords, and each ACL entry associated with that user name and
password combination might have different access permissions.
To add a user, press the “Add” button. The following dialog appears requesting the user
data. Each field is required.

40

Chapter 5 • Security Service

If the Password and the Confirm Password fields are not equal, an error occurs. An error
also occurs when the given user name and password already exist.

Removing a User
Removing a user removes the ACL entry for that user from the ACL. To remove a user,
select the user name from the list, and press the Remove button. A confirmation dialog
is posted to allow the action to be canceled.

Changing a User Password
Changing a user password updates the ACL entry for the user with the new password.
To change a user password press the “Change Password” button, and enter the required
data. A confirmation dialog will be posted to allow the action to be canceled.

Adding and Removing Permissions
User permissions are also maintained from the Manage ACL panel. Use the buttons
below the Permissions list to add and remove permissions from a user.

Adding permissions
Adding a permission adds it to the ACL entry of the selected user. To add a permission
to a user principal, select the user from the Users list, and then press the Add button
under the “Permissions” list. The following dialog appears, requesting the required data.

Voyager Administrator Guide

41

The Permission field is a drop-down list of available access permissions. The Target and
Actions fields are enabled when the chosen permission requires a target or an action.
The target refers to the entity requiring permission to be accessed. Actions refers to the
type of access allowed by the target. For example, a target might be access to a
particular file, and the actions might be read/write/execute. Choose the desired
permission and enter the required data for that permission, and then press the OK button.

Removing permissions
Removing a permission from a user removes the selected permission from the ACL
entry for that user. To remove a permission from a user, select the permission from the
permissions list, and press the Remove button. A confirmation dialog is posted to allow
the action to be canceled.

Adding and Removing Permission Types
If a developer creates a custom permission implementation, it must be added to the
Permission Types list before it can be added to a user. Use the Permissions Type panel
to add and remove permission types. The panel displays the list of permissions that can
be added to a user.

42

Chapter 5 • Security Service

To add the new permission type, the fully qualified class name of the custom permission
is required.
Permission types may also be removed from the Permission Types list. Permission types
that are removed are no longer available to add to a user, but existing instances of a
removed permission type will not be removed from the user principal. Use the buttons
below the Permission Types list to add and remove Permission types.

Adding permission types
To add a permission type, press the Add button under the Permission Types list. A
dialog is presented that prompts for the class name of the desired permission. If the class
is not found or cannot be constructed, an error occurs.

Voyager Administrator Guide

43

Removing permission types
To remove a permission type, select the permission type from the Permission Types list,
and press the Remove button. A confirmation dialog is posted to allow the action to be
canceled.

Importing Permissions
The Import button allows mass addition of user principals and their permissions. The
import function parses a file with the following format:
grant username "some user" password "users password"
{
permission com.objectspace.some.Permission "target", "actions";
permission com.objectspace.security.policy.SecurityPermission;
};
grant username "another user" password "users password"
{
permission com.objectspace.some.Permission "target", "actions";
permission com.objectspace.security.policy.SecurityPermission;
permission com.objectspace.security.policy.DirectoryPermission;
};

The import merges the users from the imported file into the existing ACL. If the import
file contains a user and password that already exist in the ACL, any new permission
from the file is added to the existing user. If a new permission type is encountered, it is
added to the Permission Types list.
To import an ACL file, press the Import button, and then select the file name from the
file dialog.

44

Chapter 5 • Security Service

Transaction Service

6

If a Voyager server was configured with the Transaction service, it has a
subfolder named Transactions in its server profile. The panels in this folder
are used to configure and monitor the transaction service. See the Voyager
Setup Guide for information on how to install the Transaction Service.
In this chapter, you will learn to:












monitor transaction statistics
view the transaction log
view active transactions
view transaction errors
communicate with the server

Note: The transaction service is only available in the Voyager Transactions
and Voyager Application Server products.

45

Monitoring Transaction Statistics
The Statistics panel allows administrators to view the runtime server usage statistics as it
relates to transactions. All statistics are relative to the time that the server was started. If
the server is not running, the value of each field is empty. Any numeric value, including
zero, indicates that the server is up and communicating with the console.

General Transaction Statistics
The following general transaction statistics are available:



46

Transactions – total number of transactions begun.

Chapter 6 • Transaction Service











Committed – number of transactions that have been committed successfully.
Rolled Back – number of transactions that were rolled back.
Heuristic Outcomes – number of heuristic decisions taken by transactional resources.
A heuristic decision is a decision to commit or rollback that is made by a resource
without waiting for the coordinator to propagate the decision. A large number may
indicate excessively long transactions or bigger problems. See "Viewing Transaction
Errors" for more information.
Active Transactions – number of transactions still in progress.

Transaction Duration Statistics
The following transaction duration statistics are available:








Minimum time – minimum transaction duration in milliseconds.
Maximum time – maximum transaction duration in milliseconds.
Average time – average transaction duration in milliseconds.

Viewing the Transaction Log
The transaction log is viewable from the Log panel. From this panel, you can view all
transactions that have occurred since the last time the log was cleared. Check the
checkbox, and set a date to view only those transactions that have occurred since the
specified date.
Choose the Heuristic outcomes radio button to filter the log so that only heuristic
outcomes are viewed. The occurrence of a heuristic outcome indicates that a
transactional resource had to make a commit/rollback decision before hearing from the
master transaction coordinator. This may happen when the transactions are excessively
long due to dropped clients, excessive client think-time, and so forth. A heuristic

Voyager Administrator Guide

47

outcome indicates a possible inconsistency in the application that should be resolved by
manually synchronizing the resources.
Note: The transaction log grows with each new transaction which can present
problems for less robust log implementations. For example, the default log
implementation logs to a file. Excessive log file size can result in reduced
performance, both for the server and the console. Use the Delete Log button to
delete the log and reduce the risk of generating an excessively large log.

48

Chapter 6 • Transaction Service

Viewing Active Transactions
The Active panel allows administrators to view information about all currently active
transactions. The display shows the transaction id (TID), transaction name (if any), and
transaction start time. Heavily loaded servers may have many thousands of active
transactions. This panel should be viewed with caution under these conditions.

Voyager Administrator Guide

49

Viewing Transaction Errors
The errors panel contains a stack dump for all errors that have occurred during an
attempt to complete a transaction. Though these stack dumps are of little administrative
value, they are important to a developer diagnosing a problem.

50

Chapter 6 • Transaction Service

Configuring Transactions
The configuration panel allows you to configure transactions.








Log Address: The URL where the transaction service will locate the logging service.
If the transaction service does not already exist at this location, Voyager will create
the transaction service at this URL. This optional feature can be useful if multiple
nodes wish to use a single logging service.
Log Factory: The name of the class implementing the ILogFactory interface that will
be created locally (if no Log Address is specified) or remotely (if specified and not
already existing). Do not change this value.
Service Address: The URL referring to a transaction factory that will create
Coordinators and Recovery Coordinators for this node.

Note: This option is not recommended as all transaction effort will result in a
significant increase in lag time due to network access.

Voyager Administrator Guide

51

Communicating with the Server
The Transaction Service Console detects whether the remote server is running, and
communicates directly with that server for statistics and log access. By default, the
console automatically refreshes every 15 seconds. To turn off the auto-refresh feature,
clear the check box. To change the refresh rate, enter it in the refresh rate field and tab
out of the field. To manually refresh the console at any time, click on the Refresh button.

52

Chapter 6 • Transaction Service

7

JDBC Service
If a Voyager server is configured with the JDBC service, it has a subfolder
named JDBC in its server profile. The panels in this folder are used to
configure JDBC datasources for a server. See the Voyager Setup Guide for
information on how to install the JDBC Service.
In this chapter, you will learn to:




configure datasource properties

Note: The JDBC service is only available in the Voyager Transactions and
Voyager Application Server products.

53

Configuring Datasource Properties
The JDBC Service allows the administrator to specify one or more JDBC datasources
for use in the application. A datasource corresponds to a particular database instance.
Datasource configuration changes are not made on-the-fly. If a modification to an
existing datasource is made or if a datasource is added or removed, the server must be
restarted to detect the change.
Each of the following properties must be specified to create a valid datasource:




Name
JNDI name to which the datasource is bound. This name should start with jdbc/ to
remain compliant to the JDBC specification. For example, if a database of employee
information is being configured as a datasource, it should be named jdbc/EmployeeDb.




Driver
Classname of the JDBC driver. The classname must be fully qualified and must be
available on the server.




URL
URL of the database. The URL identifies the actual database instance to which the
driver connects.




Login ID
Database user on whose behalf connections are made.




Login PW
Password to use with the database user identity




Initial Capacity
Number of database connections that should be created upon startup. The pool grows
as needed.




Growth Rate
Sets the rate at which database connections are created. If the pool is empty and a
connection is requested by the application, the datasource creates the number of
connections specified in this field.

54

Chapter 7 • JDBC Service




Max Capacity
Sets the maximum size of the connection pool.

Note: This parameter is not the maximum number of connections; it is the maximum
number of free-pooled connections. If the pool is full, and a connection is being
returned to the pool, the connection is not added, it is closed.

Voyager Administrator Guide

55

56

Chapter 7 • JDBC Service

8

EJB Service
If a Voyager server is configured with the EJB service, it has a subfolder
named EJB in its server profile. Two panels are associated with the EJB
subfolder: Statistics and Configuration. Three actions are associated with the
EJB subfolder: Start Container, Stop Container, and Insert Jar.
The panels and subfolders in this folder deploy new components, configure
existing components, configure the EJB container, and monitor component
and container statistics. See the Voyager Setup Guide for information on how
to install the EJB Service.
In this chapter, you will learn to:






















monitor EJB container statistics
configure the EJB container
configure an EJB service with an LDAP directory server
monitor a component’s statistics
configure a component’s general properties
view a component’s transactional properties
set a component’s security properties
set a component’s environment properties
view a method’s transactional properties
set a method’s security properties

57

Note: The EJB service is only available in the Voyager Application Server
product.

Monitoring EJB Container Statistics
The Statistics panel provides administrators a means of viewing the run-time server
usage statistics as it relates to Enterprise JavaBeans. All statistics are relative to the time
that the server was started. In addition, statistics can be viewed for the entire container
or for a given component. To view statistics on the entire server, highlight the EJB
folder in the tree. To view statistics on a given component, highlight that component in
the tree.
The following statistics are available:













58

Created – This number represents component instances created in the system. The
number of active, removed, terminated and timed out component instances must add
up to this number.
Active – This number represents the number of component instances currently in use
by clients.
Removed – This number represents the number of component instances removed
normally. A component instance is removed normally when the client removed it
through the remove method.
Terminated – This number represents the number of component instances removed by
the system. A component instance is terminated when an unhandled RuntimeException
is thrown during the execution of one of its methods. Component instances are also
terminated when an administrator stops the EJB service, disables a particular
component, or updates or deletes a jar file while the component instance is in use.
Timed Out – This number represents the number of component instances removed
because they timed out. A component instance times out when it has been in existence
for at least as long as the time-out set for the component. A component instance
typically times out when its client dies unexpectedly.

Chapter 8 • EJB Service

If the server is not running, the value of each statistic is empty. Any numeric value,
including zero, indicates that the server is up and communicating with the console. By
default, statistics automatically refresh every 15 seconds. To turn off the auto-refresh
feature, click on the check box. To change the refresh rate, enter it in the refresh rate
field, and tab out of the field. To manually refresh the statistics at any time, click on the
Refresh button.

Voyager Administrator Guide

59

Configuring the EJB Container
To configure the EJB container, the home directory URL/logical server name must be
set before starting the server. The second container configuration property is the system
identity. The system identity must be set when security is required for the server.
Note: Note for current Voyager 3.0 users: In Voyager 3.1 the logical server name has
been combined with the home directory URL. For example, if your home
directory URL was //dallas.8000 and your logical server name was FooServer, the
new home directory URL is //dallas:8000/FooServer. This becomes the full path the
server will use to store home objects. Note that the client code does not change.
Using the above example, the client would create any initial context using
//dallas:8000/FooServer for the PROVIDER_URL property.
If Voyager 3.1 is used with directory server data created with Voyager 3.0, the
logical server name will be appended to the home directory URL on the EJB
configuration panel.

The Home Directory URL and Logical Server Name
The home directory is the JNDI directory that clients use to initiate their connections to
the server. This process is known as home lookup, because it involves a JNDI lookup of
the home object of an EJB component. A description of three deployment configurations
for the home directory follow.







60

When the home directory is set to be the configuration directory server, all clients will
be performing their home lookup on the directory server that the management console
uses to store server configuration information. this configuration is not recommended.
It is generally preferred to keep the clients and the administration separate, thereby
reducing the risk of security violations, data contamination, and so forth. To deploy
with this configuration, put the hostname and port of the configuration directory in the
Home Directory URL field.
In the server configuration, a server binds its home objects in memory, and clients
connect directly to the server to perform home lookup. This is the easiest to configure,
but does not scale well. It is considered a reasonably lightweight configuration. To

Chapter 8 • EJB Service

deploy in this configuration, put the hostname and port of the server whose profile is
being edited in the Home Directory URL field.




When a second directory server runs, the directory server is dedicated to the task of
providing clients with home lookup. A directory server is started, and multiple servers
are configured to bind their homes into this directory. This configuration removes the
burden of home lookup from each server but allows for a centralized directory lookup.
To deploy with this configuration, put the hostname and port of a directory server in
the Home Directory URL field. Start this directory before starting the servers.

For all configurations, set the Logical Server Name to some value. This value does not
have to be the same name as the server profile name. They are usually different. The
logical server name provides an abstraction layer between the physical server and
clients. This name can be any string, as long as it is unique to the server.

Note: Future versions of Voyager will allow multiple servers to share a logical server
name. In this configuration, a logical server name includes a cluster of physical
servers to support load-balancing and fault-tolerance.
Changes to the directory URL and server name do not affect a running server. Restart
the server to take advantage of the modified settings.
The logical server name becomes a JNDI context into which all home objects for this
server are bound. Clients can therefore connect to the URL created by the concatenation
of the home directory URL and logical server name. For example, assume the directory
is on the local host, the logical server name is FooServer, and the bean home name is
FooHome. The following code allows a client to look up the home object:
Hashtable env = new Hashtable();
env.put( Context.PROVIDER_URL, "//localhost:8000/FooServer" );
InitialContext ctx = new InitialContext( env );
IFooHome home = (IFooHome) ctx.lookup( "FooHome" );

Note: If the Voyager server and the Directory Server are running in the same VM, the
logical server name should not be set to anything.

Voyager Administrator Guide

61

Finding Home Objects
When using JNDI to find EJB home objects in an LDAP directory server, the
objectspace.directory.server.implementation property must be added to the JNDI properties
Hashtable prior to creating the initial context and looking up the home object for the
bean. Its value must be ldap. For example:
java.util.Hashtable properties = new java.util.Hashtable();
properties.put(
java.naming.Context.INITIAL_CONTEXT_FACTORY,
“com.objectspace.voyager.jndi.spi.VoyagerContextFactory” );
properties.put(
“objectspace.directory.server.implementation”,
“ldap” );

Voyager’s initial context factory must always be specified as the
INITIAL_CONTEXT_FACTORY property. When using Voyager with a naming or directory
implementation other than Voyager Directory Server, Voyager’s initial context factory
will delegate the creation of initial contexts to an initial context factory from an alternate
service provider, such as Sun’s LDAP provider. If an alternate service provider is used,
Voyager will add Voyager-specific functionality to the initial context returned from the
alternate service provider’s initial context factory before returning it to the client. Please
refer to the Voyager Administration Guide Addendum for more information regarding
JNDI configuration.
When used with LDAP, Voyager will use Sun’s LDAP service provider by default. An
alternate LDAP provider can also be used. To use an initial context factory from an
alternate service provider when accessing LDAP servers, add the
objectspace.alternate.factory.initial property to the JNDI properties Hashtable. For example:
java.util.Hashtable properties = new java.util.Hashtable();
properties.put(
java.naming.Context.INITIAL_CONTEXT_FACTORY,
“com.objectspace.voyager.jndi.spi.VoyagerContextFactory” );
properties.put(
“objectspace.directory.server.implementation”,
“ldap” );
properties.put(
“objectspace.alternate.factory.initial”,
“com.some.alternate.LDAPContextFactory” );

62

Chapter 8 • EJB Service

System Identity
The container uses the System Identity field when a component’s security run-as mode
is set to System. The field allows a component to invoke another component as the
system. The field is also used to connect to the home directory and should have
directory permissions when the directory is secured.

Administrators can stop all usage of EJB components by clicking on the Stop button (for
example, to perform server maintenance). Stopping the EJB container removes all active
component instances, and component instances are identified as Terminated in the
Statistics panel. If the component instance is associated with a container-managed or
bean-managed transaction, the transaction is rolled back. If the component instance is
associated with a client-managed transaction, the transaction is marked for rollback.
Any component instances in the process of fulfilling a client request completes before
being removed. To restart the EJB Container, click on the Start button.
New components are deployed into a system from the standard EJB jar file format using
the Insert Jar button. The server does not need to be running. The components are not
enabled until the administrator explicitly enables each component, allowing the

Voyager Administrator Guide

63

administrator to fully customize the home name, session time-out, environment
properties, and security properties before the components are available to clients.
To insert a jar into the EJB Service, click on the Insert Jar button. A dialog opens asking
you to find the jar file in your file system. When inserting a jar, any errors found in the
components are written to the output panel. If any errors occur that prevent the
component from running in the EJB Service, the component is not added.
A node is in the directory tree for each jar deployed into a server. No panels are
associated with managing jar files. However, there are two actions associated with a jar:
Update and Delete. These actions are available from the tool bar and from pop-up menu
associated with the jar node.

A deployed jar file must be updated as new versions of its components are released. To
update a deployed jar file, click on the jar node in the tree and then click on the Update
button. Select the new version of the jar file from the file system. If any of the classes in
64

Chapter 8 • EJB Service

the jar file changed, stop the server while the jar file is being updated. When updating jar
files, if a component was already deployed and is being updated by the jar file, the
following properties are not updated, because the deployment information is typically
more appropriate.








Bean Home Name
Session Timeout
All Security Properties

The following properties use the values from the new jar file:












Bean Class
Home Interface
Remote Interface
Bean Type
All Transaction Properties

Environment properties merge, and new properties from the new jar file are added.
Properties removed from the new jar file are removed. Properties that exist in both the
deployed jar and the new jar file use the deployed jar file’s values, because since the
appropriate values are better known at deployment time, they are kept.
The Update Jar action can be performed whether or not the server is running. However,
changes are not reflected in the server until it is restarted.
To delete a deployed jar file, click on the jar node in the directory tree, and then click on
the Delete button. Deleting a jar removes all of its components from the configuration
directory. It also removes all of its components from the server when the server is
currently running. If any of the components have active instances, these instances are
removed and identified as Terminated in the statistics panel. If a component instance is
associated with a container-managed or bean-managed transaction, the transaction is
rolled back. If a component instance is associated with a client-managed transaction, the
transaction will be marked for roll back. Any component instances that are in the
process of fulfilling a client request complete the request before being removed.
The component nodes allow administrators to configure those aspects of a component
that are not design decisions. Configuration changes do not immediately take affect, you
must click on the Apply button first to apply all changes to the deployed component. To

Voyager Administrator Guide

65

cancel your changes, click on the Cancel button. The statistics refresh rate takes effect
immediately, and does not require pressing the Apply button.

66

Chapter 8 • EJB Service

Configuring an EJB Service with an
LDAP Directory Service
The EJB service configuration panel in the VMC allows the user to specify the JNDI
environment properties of the directory server that will contain the home objects.

To specify that bean home objects should be stored in an LDAP directory server, enable
the Replace System Properties check-box, and enter the necessary system properties.
The following table summarizes the properties that must be specified.

Voyager Administrator Guide

67

Key

Value

objectspace.directory.server.implementation

ldap

java.naming.factory.initial

com.objectspace.voyager.jndi.spi.VoyagerContext
Factory

java.naming.security.authentication

simple

java.naming.security.principal

A simple text-string user name that will be
used to log into the directory server.

java.naming.security.credential

A simple text-string password that will be
used to log into the directory server.

Other properties may be required depending on the JNDI service provider and the
LDAP directory server implementation.
To use an initial ContextFactory other than Sun’s, use the objectspace.alternate.factory.initial
property.

68

Chapter 8 • EJB Service

Monitoring a Component’s Statistics
The statistics provided in the component Statistics panel are identical to the statistics
provided in the EJB container Statistics panel except that the statistics provided here
apply to the currently selected component only. For example, the Active statistic relates
the current number of active instances of this component, not the total number of active
instances across all components.

Voyager Administrator Guide

69

Configuring a Component’s General
Properties
The General panel contains general properties about the component, which include the
bean class, home interface and remote interface specified at creation as well as the bean
home name, bean type, and time-out.

70

Chapter 8 • EJB Service

Home Name
Clients can create a component instance by placing its home object in a well-known
location in JNDI. The bean home name specifies the JNDI location where the home
object should be put. Clients must know this name to create an instance.

Bean Type
The bean type is determined during design. This information is not editable by
administrators and is displayed for informational purposes only.

Specifying the Session Timeout
Session components are used for a period of time by the client and then removed by the
client. A problem occurs when the client dies before removing the component instance.
The component instance never gets removed and therefore consumes server resources
unnecessarily. This is exactly the problem that time-outs are intended to solve. The
timer starts when the component instance is created. If the component instance has not
been removed by the time the time-out has finished, it is automatically removed by the
system. The default time-out is 24 hours.

Voyager Administrator Guide

71

Viewing a Component’s Transactional
Properties
The transactional properties of a component are viewable from Transactions panel.
These properties are decided during design, so an administrator cannot alter them.

72

Chapter 8 • EJB Service

Setting a Component’s Security
Properties
Use the Security panel is used to set the security properties for a component. Two
aspects of security are managed by the EJB container:






The container allows or denies access to a component or particular methods on a
component based on the identity of the client
The EJB container sets the identity that is used when a component interacts with
another component. The identity is compared to the client identity based on the
security policy.

Voyager Administrator Guide

73

Allowed Identities
The users in the Allowed Identities list are the only users that can access the specified
component or method. The one exception to this rule is that if no users are in the list,
everyone has access to the component. To insert a new allowed identity, click on the
Insert button, and select the correct user. To remove an allowed identity, select it in the
list, and click on the Remove button.
When calling other components, choose one of three options to determine the identity to
use:




74

Client Identity – If Client Identity is chosen, the identity associated with the current
client is used when interacting with other components.

Chapter 8 • EJB Service






System Identity – If System Identity is chosen, the system identity is used when
interacting with other components. The system identity is a special identity specified
by Voyager that has system privileges.
Specified Identity – If Specified Identity is chosen, the administrator-specified user
identity is used when interacting with other components. By default, this is None,
which means that no identity is used. To select a specified identity, click on the
Specified Identity radio button to select the mode, click on the Browse button, and
select the correct user identity. Specified Identity is the default value for interacting
with other components, with no specified identity. As a result, no identity is
propagated to called components by default.

Setting a Component’s Environment
Properties
When developing a component, properties cannot be determined until deployment. For
example, a component might use JDBC to interact with a database. Leave the location of
the database open, so that it can change at deployment. Environment properties allow
administrators to specify runtime characteristics of the component. The environment
properties that are used are completely at the discretion of the component developer.
Typically, default values for the environment properties are put in at development time.
The administrator then customizes the values.

Voyager Administrator Guide

75

To insert a new environment property, click on the Add button and insert a new row. To
change the property name or value, click on the cell, and type the new name or value. To
remove a property, click on any cell in the row, and click on the Remove button.
Administrators can stop all usage of an EJB component by clicking on the Disable
button (for example, to perform maintenance). Disabling a component prevents any new
client connections and removes all active component instances which are identified as
Terminated in the statistics panel. If the component instance is associated with a
container-managed or bean-managed transaction, the transaction is rolled back. If the
component instance is associated with a client-managed transaction, the transaction is
marked for roll back. Any component instances that are in the process of fulfilling a
client request complete the request before removal. To restart the component, click on
the Enable button.

76

Chapter 8 • EJB Service

Note: It is now possible to select multiple beans for simultaneous enable/disable.

Note: The Enable/Disable state of a component is persistent. The Start/Stop state of a
container is not maintained across server restarts, whereas the enable/disable
state of a component is maintained. For example, if a component is disabled and
the server is later taken down, the component is still disabled the next time that
server is restarted.
The method nodes let administrators view and configure component properties at the
method level. These properties override the settings specified at the component level.

Note: A method that overrides a component’s properties with custom properties is
indicated in the directory tree with a different icon.

Voyager Administrator Guide

77

Viewing a Method’s Transactional
Properties
The transactional properties of a method are viewable from Transactions panel. These
properties may override the component’s properties. This information is not editable by
administrators and is displayed for informational purposes only.

78

Chapter 8 • EJB Service

Setting a Method’s Security Properties
The method’s Security panel allows administrators to specify security at a finer level of
detail than is possible by setting security properties on the component level. This detail
is when particular component actions must be restricted to a subset (or opened to a
superset) of the clients capable of accessing the component. Security settings made on a
method override the settings specified at the component level.

Voyager Administrator Guide

79

80

Chapter 8 • EJB Service