Administrator's Guide

Chapter 11   Using the Server Administration API

The SilverStream Server is fundamental to all of your design time and run time activities, so it requires some configuration and management. You can perform these configuration and management tasks using the SilverStream Management Console (SMC) provided with the SilverStream Server, or you can create your own management console (or parts of a management console) using the Server Administration API. The SMC is built using this API. Applications that are written using this API can be deployed as an HTML page in a browser or as a form in a Java client, such as SilverJRunner or an externally developed Java client.

This chapter introduces the Server Administration API. It provides information about the following sections:

This chapter provides the conceptual framework that you need for using the Administration API. Use the following resources for more information:

    For programming examples that illustrate specific management tasks, see Administration Techniques in the online Application Techniques.

    For information about developing applications inside and outside of the SilverStream IDE, see the chapter on coding Java in the Programmer's Guide.

    If you are unfamiliar with the architecture of the SilverStream Server, or do not have a working knowledge of SilverStream databases, security, and load balancing, you can find more information about them in this book. For example:

Introduction to the Administration API   Top of page

The Administration API makes any server-registered object available for configuration or management. A registered object is any resource that resides on and is known to the server. Examples of server-registered objects range from SilverStream forms, views, and pages, to SilverStream users and groups, to load balancing clusters.

You can use the Administration API to write applications that let end users, system administrators, or batch processes do a variety of tasks. For example, you can use the API to allow end users to change their passwords, to let system administrators change permissions on a SilverStream business object, or to delete a registered object from the server.

Administering the application server involves:

The API provides method calls to perform both types of tasks. You can use the API to gain access to objects that represent all of the following:

The Administration API also provides access to server cache and port-related settings through the AgiAdmServer interface.

Client-side vs. server-side access to API

The Administration API is available to Java-based forms, HTML-based pages, and business objects. However, since forms are client-based and HTML pages and business objects are server-based, there are some differences in the objects and in the functionality that is available to you. For this reason, it is important to know how you will deploy the application before you get started.

The following functions are restricted to client-side implementation of the Administration API:

You can only programmatically access database connection pools from the server-side of the API, that is, from business objects and pages.

How the Administration API is organized   Top of page

You can easily determine which features or objects can be managed based on the package in which the interface or class that represents that object resides. The Administration API is available through these packages:

The following diagram illustrates how these packages are organized, and the classes and interfaces included in each package. As shown, the com.sssw.rts.adminapi package is available to both the client and the server.

How server objects are organized   Top of page

Before you can work with server-related objects, you should understand more about how the Administration API represents objects and how the server organizes them.

The SilverStream Server contains two types of objects: objects that can contain other objects (containers) and objects that cannot (elements). The server organizes these objects in a hierarchy within each SilverStream database.

A single SilverStream Server (represented by the AgiAdmServer object) can contain multiple databases. Every SilverStream database (represented by AgiAdmDatabase objects) contains multiple directories (represented by AgiAdmDirectory objects). Servers, databases, and directories are all containers.

If you are familiar with the SilverStream design environment, then this directory structure will be quite familiar as there is a directory for each of the SilverStream designers, including forms, views, tables, pages, and business objects.

Because an AgiAdmDirectory object is a container, it can contain other directory objects as well as single elements. The types of elements that a directory can contain depends on the directory. For example:

The object hierarchy

Here is how the objects are structured on the SilverStream Server:

      AgiAdmDirectory.SECURITY (see next section)

The security objects

As shown in the previous hierarchy, there is a Security directory on the server. It has its own hierarchy of objects that are related to the security realms that SilverStream supports. Here is the Security hierarchy:


The load balancing object hierarchy

The load balancing objects are not contained within the database/directory hierarchy as are the other server containers and elements. However, they do follow the same container/element paradigm.


More about containers and elements   Top of page


All server objects are elements. A database is an element, a load balancing cluster is an element, a SilverStream user is an element, a Java form is an element, and so on.

All server objects (except the load-balancing objects) implement the AgiAdmElement interface, which means that you can perform similar functions on all objects. For example, you can get the object's name and its type, and you can get and set permissions for it.

If you have a server object, you can obtain any other object by calling AgiAdmServer.getElement().

    For information on obtaining a server object, see Getting started with the Administration API.

Element hierarchy

This diagram illustrates the hierarchy for the interface objects that represent elements on the server.

Elements and containers

Some elements are also containers. A container is an element that can contain (or can parent) other elements. The server elements that are also containers include servers, databases, directories, groups, and load balancing containers. Containers implement the AgiAdmContainer interface.

You can perform a specific set of functions on container elements, such as enumerating the children of the container, obtaining a specific child, and adding children.

Container hierarchy

This diagram illustrates the container hierarchy.

The programming environment   Top of page

The programming environment differs with the deployment strategy that you are using.

    For information on using the SilverStream tools, see the Form Designer, Page Designer and Business Object Designer chapters in the online Tools Guide.

NOTE   You cannot add your own custom applications to the SilverStream Management Console.

Getting started with the Administration API    Top of page

Your first programming task, before you have access to any server objects, is to obtain a reference to a server object (AgiAdmServer for client-based applications or AgiServer for server-based applications). Once you have the server object, you can obtain and manipulate any of its elements.

You do not need a server object if you intend to work with the publish manager (AgiAdmPublishMgr) or the expression manager (AgiAdmExpressionMgr).

Obtaining a server object from a client application   Top of page

You can obtain a server reference by calling the AgAdmin.getServer() method with three variants. You need the following imports:

  import com.sssw.rts.adminapi.*; 
import com.sssw.rts.adminclient.*;

Variant one

One variant lets you specify the server name and its port:

  AgiAdmServer getServer(String serverName, int port)  
throws AgoUnrecoverablSystemException

where serverName is the name of the server, and port is the port to use (specify -1 to use the default port).

For example:

  AgiAdmServer srv = AgAdmin.getServer("myserver", 90); 

Variant two

The second variant also lets you specify either the HTTP or HTTPS protocol.

  AgiAdmServer getServer(String protocol, String serverName, int port)  
throws AgoUnrecoverableSystemException

For example:

  AgiAdmServer srv = AgAdmin.getServer("https", "myserver", 88); 

Variant three

The third variant lets you specify the server, its port, and the protocol as one string:

  AgiAdmServer getServer(String server)  
throws AgoUnrecoverableSystemException

For example:

  AgiAdmServer srv = AgAdmin.getServer("https://myserver:8080"); 

Using getServer

The getServer() method returns an object of type AgiAdminServer. Once you have this object, you can get its properties, enumerate its objects (containers and/or elements), and manipulate the elements.

Obtaining a server object from a server application   Top of page

If you are trying to manage the server from a page or business object, you must use the AgiServer interface to obtain the server object.

AgiServer is the main server-side interface extending AgiAdmServer. An initialized instance of AgoServer is passed to server-side objects using the getServer() method on the event object passed to the page or business object.

From a page

Code the following:

  AgoHttpRequestEvent evt = (AgoHttpRequestEvent) getCurrentRequest(); 
AgiServer srv = evt.getServer();

From a business object

Code the following:

  AgiServer srv = evt.getServer(); 

    For more information on obtaining objects (such as an AgiServer) from an event object, see the triggered object basics chapter in the Programmer's Guide.

Getting a server's properties   Top of page

Once you have the AgiAdmServer or the AgiServer object, you can access any of the server's properties. This example shows how you can get two server properties using the client-side API (AgAdmin).

First, make sure you have the proper imports in the form:

  import com.sssw.rts.adminapi.*; 
import com.sssw.rts.adminclient.*;

The following code gets two properties--the name of the SilverMaster database and the DSA port--then displays the values in text fields on a form.

  try { 
AgiAdmServer srv = AgAdmin.getServer("localhost",80);

// Get the name of the SilverMaster database
String sSMaster =
(String) srv.getProperty(srv.PROP_SILVERMASTER);

// Get the DSA port used by the server
Integer iDSAport =
(Integer) srv.getProperty(srv.PROP_HTTPS_DSA_PORT);

// Display the values in text fields


catch (Exception e) {

You can use the same technique on the server (in pages and business objects), except you would obtain the server object using the server-side API. Instead of importing com.sssw.rts.adminclient.*, you would import com.sssw.srv.api.*.

Working with server elements   Top of page

Once you have the AgiAdmServer or the AgiServer object, you can access any of its elements. There are several ways that you can obtain and manipulate those elements:

Enumerating database elements

This example illustrates how to obtain a server object, enumerate the databases that reside on the server, and enumerate the elements within each database. It shows how to obtain the server object using the client-side API (AgAdmin). You can use the same technique on the server, except you would obtain the server object using the server-side API.

First, make sure you have the proper imports in the form:

  import com.sssw.rts.adminapi.*; 
import com.sssw.rts.adminclient.*;

Next, get the server and enumerate the database elements:

  try { 
  // Get a server and enumerate the databases within it
  AgiAdmServer server = AgAdmin.getServer("", 90);
  Enumeration databases =

  // For each database in the enumeration, get to a database
  while(databases.hasMoreElements()) {
AgiAdmDatabase db =

  // Enumerate the 'well-known' directories within the database
  Enumeration directories =

  // For each directory enumerate the design elements
while(directories.hasMoreElements()) {
AgiAdmDirectory dir =
Enumeration desElements =
  // For each design element, you can do something with it...
AgiAdmDesignElement desEl =
 // Perform an action on the design element here
catch (Exception e) {

These notes explain the code.

  1. Obtain a reference to the server at port 90.

  2. Enumerate the application databases that reside on the server.

  3. For each database, enumerate its directories.

  4. After you have the enumeration of the objects, you can manipulate the design element, such as setting permissions for it or deleting it.

Obtaining elements using getElement()

The getElement() method obtains an object with the specified name and type. It provides a shortcut for instantiating new server objects. This is the declaration:

  AgiAdmElementBase getElement(String name, String type, 
Hashtableinfo) throws AgoUnrecoverableSystemException,

The name parameter specifies the name of the element. (For example, a form named myForm, a database table named Customers, a page named HomePage, and so on).

The type parameter specifies the object type of the element that you want to obtain, including the constant. (For example, to obtain an element whose type is form, you specify AgiAdmDesignElement.FORM.)

There are types for each kind of known element, including:

You use a constant to specify its type.

The info parameter is a Hashtable that contains additional pieces of information that are necessary to identify the object you want to obtain via getElement(). You use the put() method on a Hashtable to insert additional information into the info parameter.

The info parameter can be one of these constants:

This example illustrates how to obtain a server element of type AgiAdmDatabase where the database name is Montreal and the element type is AgiAdmDatabase.DATABASE. The info parameter is specified as null because the AgiAdmDatabase.DATABASE does not require it.

  AgiAdmServer server = AgAdmin.getServer("myserver",80); 
AgiAdmDatabase myDB = (AgiAdmDatabase)server.getElement("Montreal",
AgiAdmDatabase.DATABASE, null);

More about the info parameter

The following table lists additional information about item identifiers that you can use with the info parameter and the elements to which they are related.

Information item identifier

Elements used by




AgiAdmDesignElement, AgiAdmDirectory




AgiAdmUser.NTUSER, AgiAdmGroup.GROUP, AgiAdmDirectory.NTUSERS, AgiAdmDirectory.NTGROUPS


AgiAgmDesignElement.APP_OBJECT, AgiAdmDirectory.PACKAGE, AgiAdmDirectory.DIRECTORY, AgiAgmDesignElement.SERVLET


AgiAdmDirectory.LDAPGROUPS, AgiAdmDirectory.LDAPUSERS, AgiAdmUser.LDAPUSER, AgiAdmGroup.LDAPGROUP



This example shows how you can put the port number value into a Hashtable and pass it to the AgiAdmServer.getElement() method on the info parameter:

  Hashtable info = new Hashtable(); 
info.put(AgiAdmServer.INFO_PORT_NUMBER, new Integer(92));
AgiAdmServer anotherServer=
(AgiAdmServer) myServer.getElement("redhook",AgiAdmServer.SERVER,

This example shows how you can use a Hashtable to populate the info parameter with data for the INFO_GROUP_NAME:

  Hashtable info=new Hashtable(); 
info.put(AgiAdmServer.INFO_GROUP_NAME, "Administrators");
AgiAdmUserReference uref=
AgiAdmUserReference.USER_REFERENCE, info);

Obtaining child elements

Many objects on the server are parents or children of other elements (or containers). This container relationship is useful for obtaining a reference to an object.

As you saw earlier in the chapter, the server is the parent of all of the objects on the server. Any SilverStream database is a child of the server. You can use the AgiAdmContainer.getChild() method to obtain a single child of a particular container, or the AgiAdmContainer.getChildren() to enumerate all of the children.

The getChild() method has this declaration:

  AgiAdmElementBase getChild(String name, String type, 
Hashtable info) throws AgoUnrecoverableSystemException,

where name is the name of the child, type is the object type of the child, and info includes any additional properties describing the child.

This example that shows how to obtain a reference to the server, obtain a database named myDatabase, and obtain the directory of FORM objects:

  // get a reference to AgiAdmServer 
AgiAdmServer server = ...

// get database (a child of server)
AgiAdmDatabase database = (AgiAdmDatabase)server.getChild(
"myDatabase", AgiAdmDatabase.DATABASE, null);

// get the FORMS directory (a child of database)
Hashtable info = new Hashtable();
info.put(AgiAdmServer.INFO_DATABASE_NAME, "myDatabase");
AgiAdmDirectory formsDir = (AgiAdmDirectory)database.getChild
(AgiAdmDirectory.FORMS, AgiAdmDirectory.FORMS, info);

You can call getChild() on any container-type objects.

Where to go from here   Top of page

Now that you have seen the packages that contain the Administration API and the ways that objects are referenced on the server, you might be wondering how to start writing applets or applications that use these classes, or wondering where to start.

The following table lists some common tasks and the interfaces you can use to implement them.


Interfaces to use

Load balancing configuration

AgiAdmLBClusterEnv, AgiAdmLBContainer, AgiAdmLBElement



Set security on objects

AgiAdmExpressionMgr (and the interfaces that let you obtain the object, for example, AgiAdmDesignElement)

Work with design elements


Manage server sessions


Manage mail accounts


Manage certificates


Manage SilverStream Licenses


Manage deployed Enterprise JavaBeans


Manage threads


Manage statistics

AgiAdmStatistics, AgiAdmStatSet

    For examples, see Administration Techniques in the online Application Techniques.

Copyright © 2000, SilverStream Software, Inc. All rights reserved.