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:
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.
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.
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:
AgiAdmServer.SERVER
AgiAdmDatabase.DATABASE
AgiAdmDirectory.APP_OBJECTS
AgiAdmDirectory.PACKAGE
AgiAdmDesignElement.APP_OBJECT
AgiAdmDirectory.PACKAGE
AgiAdmDirectory.PACKAGE
AgiAdmDesignElement.APP_OBJECT
AgiAdmDirectory.FORMS
AgiAdmDesignElement.FORM
AgiAdmDirectory.TABLES
AgiAdmDesignElement.TABLE
AgiAdmDirectory.VIEWS
AgiAdmDesignElement.VIEW
AgiAdmDirectory.MEDIA
AgiAdmDirectory.GENERAL
AgiAdmDesignElement.GENERAL_ELEMENT
AgiAdmDirectory.IMAGES
AgiAdmDesignElement.IMAGE
AgiAdmDirectory.JARS
AgiAdmDesignElement.JAR
AgiAdmEjbJar.EJB_JAR
AgiAdmDirectory.SOUNDS
AgiAdmDesignElement.SOUND
AgiAdmDirectory.PAGES
AgiAdmDesignElement.PAGE
AgiAdmDirectory.DIRECTORY
AgiAdmDirectory.DIRECTORY
AgiAdmDesignElement.SERVLET
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:
AgiAdmDirectory.SECURITY
AgiAdmDirectory.SILVER_SECURITY
AgiAdmDirectory.SILVERGROUPS
AgiAdmGroup.SILVERGROUP
AgiAdmUserReference.USER_REFERENCE
AgiAdmDirectory.SILVERUSERS
AgiAdmUser.SILVERUSER
AgiAdmDirectory.NT_SECURITY
AgiAdmDirectory.DOMAIN
AgiAdmDirectory.NTGROUPS
AgiAdmGroup.NTGROUP
AgiAdmUserReference.USER_REFERENCE
AgiAdmDirectory.NTUSERS
AgiAdmUser.NTUSER
AgiAdmDirectory.LDAP_SECURITY
AgiAdmDirectory.LDAP_SERVER
AgiAdmDirectory.LDAPUSERS
AgiAdmUser.LDAPUSER
AgiAdmDirectory.LDAPGROUPS
AgiAdmGroup.LDAPGROUP
AgiAdmUserReference.USER_REFERENCE
AgiAdmDirectory.NISPLUS_SECURITY
AgiAdmDirectory.NISPLUS_SERVER
AgiAdmDirectory.NISPLUSUSERS
AgiAdmUser.NISPLUSUSER
AgiAdmDirectory.NISPLUSGROUPS
AgiAdmGroup.NISPLUSGROUP
AgiAdmUserReference.USER_REFERENCE
AgiAdmDirectory.CERTIFICATE_SECURITY
AgiAdmUser.CERTIFICATEUSER
AgiAdmGroup.WORLD
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.
AgiAdmLBClusterEnv.CLUSTER_ENV
AgiAdmCluster.CLUSTER
AgiAdmClusterServer.CLUSTER_SERVER
AgiAdmLBContainer.CACHE_MGR_GROUP
AgiAdmLBElement.CACHE_MGR
AgiAdmLBContainer.LOAD_MGR_GROUP
AgiAdmLBElement.LOAD_MGR
AgiAdmLBContainer.DISP_GROUP
AgiAdmLBElement.DISPATCHER
Elements
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 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.
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.
AgAdmin.getServer() method.
For more information, see
Obtaining a server object from a client application.
For more information, see
Obtaining a server object from a server application.
You do not need a server object if you intend to work with the publish manager (AgiAdmPublishMgr) or the expression manager (AgiAdmExpressionMgr).
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).
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
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
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.
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
AgoHttpRequestEvent evt = (AgoHttpRequestEvent) getCurrentRequest();
AgiServer srv = evt.getServer();
From a business object
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.
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
Field1.setText(sSMaster);
Field2.setText(iDSAport.toString());
}
catch (Exception e) {
System.out.println(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.*.
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:
AgiAdmServer.getElement() method. This option is a shortcut to obtaining a specific element and is useful when you want only a single element.
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("dg.myHome.com", 90);
Enumeration databases =
server.getChildren(AgiAdmContainer.GET_CHILDREN_SORTED);
// For each database in the enumeration, get to a database
while(databases.hasMoreElements()) {
AgiAdmDatabase db =
(AgiAdmDatabase)databases.nextElement();
// Enumerate the 'well-known' directories within the database
Enumeration directories =
db.getChildren(AgiAdmContainer.GET_CHILDREN_SORTED);
// For each directory enumerate the design elements
while(directories.hasMoreElements()) {
AgiAdmDirectory dir =
(AgiAdmDirectory)directories.nextElement();
Enumeration desElements =
dir.getChildren(AgiAdmContainer.GET_CHILDREN_SORTED);
// For each design element, you can do something with it...
while(desElements.hasMoreElements())
{
AgiAdmDesignElement desEl =
(AgiAdmDesignElement)desElements.nextElement();
// Perform an action on the design element here
}
}
}
}
catch (Exception e) {
System.out.println(e);
}
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,
AgoSecurityException
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.
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,
info);
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)server.getElement("admin1",
AgiAdmUserReference.USER_REFERENCE, info);
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,
AgoSecurityException
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.
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.
AgiAdmExpressionMgr (and the interfaces that let you obtain the object, for example, AgiAdmDesignElement) | |
For examples, see Administration Techniques in the online Application Techniques.