com.hcl.domino.admin

Interface ServerAdmin

public interface ServerAdmin

Server administration features and console access

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	ServerAdmin.AclLevelRelation
static class	ServerAdmin.ClusterLookup These values are used as input to the getServerClusterMates(String, ClusterLookup) function. When you specify the ServerAdmin.ClusterLookup.LOOKUP_NOCACHE value, the call retrieves the input server's cluster member list through a NameLookup on the input server. The client cluster cache is not used for determining this information. When you specify the ServerAdmin.ClusterLookup.LOOKUP_CACHEONLY value, the call is forced to retrieve the server's cluster member list from the local client cluster cache. There is no NameLookup performed on the server in this case.
static interface	ServerAdmin.ConsoleHandler Handler to receive a server console line with text and meta data
static interface	ServerAdmin.DominoSSOToken SSO Token for a Domino username and server
static interface	ServerAdmin.MultiDatabaseAccessInfo
static interface	ServerAdmin.RegistrationMessageHandler

Method Summary

Modifier and Type	Method and Description
ServerAdmin.MultiDatabaseAccessInfo	computeDatabaseAccess(String server, String username, boolean forceNewScan) Using this method you can efficiently scan a server directory and compute the AclAccess of users on the databases.
ServerAdmin.MultiDatabaseAccessInfo	computeDatabaseAccess(String server, UserNamesList user, boolean forceNewScan) Using this method you can efficiently scan a server directory and compute the AclAccess of users on the databases.
ServerStatusLine	createServerStatusLine(String taskName) Creates a new status line for the given name.
ServerAdmin.DominoSSOToken	generateSSOToken(String orgName, String configName, String userName, TemporalAccessor creationDate, TemporalAccessor expirationDate, boolean enableRenewal) Generates a new SSO token on the current server
List<String>	getServerClusterMates(String serverName, ServerAdmin.ClusterLookup lookupMode) This function retrieves a list of server names that belong to the same cluster as the specified server. If the serverName parameter is NULL then the function retrieves the cluster members of the user's home server. The lookupMode parameter controls how the information is retrieved. If the ServerAdmin.ClusterLookup.LOOKUP_NOCACHE flag is specified then the information is retrieved using a NameLookup on the server only. If the ServerAdmin.ClusterLookup.LOOKUP_CACHEONLY flag is specified then the information is retrieved using the client's cluster name cache. If no flag (a value of NULL) is specified, then the information is retrieved first through the client's cluster name cache and if that is not successful, then through a NameLookup on the server. Note that the list returned does not include the input server name (or home server name if NULL was specified). getServerClusterMates(String, ClusterLookup) uses the Address book specified by the user's location record. Unless cascading Address books or Directory Assistance is enabled, the Notes mail domain field in the user's location record must be set to the domain name for the server(s) in the cluster and the Home/mail server field must be set to a server in this domain. If the target server is in a different domain than specified in the user's location record then in order for getServerClusterMates(String, ClusterLookup) to succeed, you must have cascading Address books or Directory Assistance enabled and the target domain's Address book must be in the list of Address books to be searched.
UserNamesList	getUserNamesList(String server, String username) Compute the name variants and groups of this user on the provided server.
void	logMessage(String messageText) Logs a message to the server using the Addin API.
void	markInService(String server, String filePath) This function marks a cluster database in service by clearing the database option flag OUT_OF_SERVICE, if set. When a call to markInService(String, String) is successful, the Cluster Manager enables users to access the database again by removing the "out of service" access restriction. Traditional Domino database access control list (ACL) privileges apply under all circumstances.
void	markOutOfService(String server, String filePath) This function marks a cluster database out of service for remote user sessions by modifying the database option flags to include OUT_OF_SERVICE. When this operation is successful, the Cluster Manager denies any new user sessions for this database. This restriction is in addition to any restrictions set forth in the database access control list (ACL). The purpose of this function is allow the system administrator to perform maintenance on a database without requiring a server shutdown or having to use the database ACL to restrict access. In order to use markOutOfService(String, String) with a database on a clustered server, the remote Notes user must have at least designer access privileges. If a user's privilege level is insufficient, a database access error is returned. The markOutOfService(String, String) function affects only databases that reside on Domino clusters. You can mark a database back in service by calling the markInService(String, String) function. For more information, see the Domino Administration Help database.
void	openServerConsole(String serverName, ServerAdmin.ConsoleHandler handler) Opens a remote console for the specified server
void	registerCrossCertificate(String certFilePath, String certPW, String certLogPath, DominoDateTime expirationDateTime, String regServer, Path idFilePath, String comment, ServerAdmin.RegistrationMessageHandler msgHandler) This function will cross-certify an ID with another organization's hierarchy. It will open the Domino Directory (Server's Address book) on the specified registration server, verify write access to the book, and add a new Cross Certificate entry.
String	sendConsoleCommand(String server, String command) Sends a console command to a Domino server

Method Detail

markInService

void markInService(String server,
                   String filePath)

This function marks a cluster database in service by clearing the database option flag OUT_OF_SERVICE, if set.

When a call to markInService(String, String) is successful, the Cluster Manager enables users to access the database again by removing the "out of service" access restriction.

Traditional Domino database access control list (ACL) privileges apply under all circumstances. In order to use markInService(String, String) on a database in a cluster, the remote Notes user must have at least designer access privileges for the specified database. If a user does not have the proper privileges, a database access error is returned.

The markInService(String, String) function only affects databases within a Lotus Domino Server cluster.

For more information, see the Domino Administration Help database.

Parameters:

server - db server

filePath - db filepath

markOutOfService

void markOutOfService(String server,
                      String filePath)

This function marks a cluster database out of service for remote user sessions by modifying the database option flags to include OUT_OF_SERVICE.

When this operation is successful, the Cluster Manager denies any new user sessions for this database.
This restriction is in addition to any restrictions set forth in the database access control list (ACL).
The purpose of this function is allow the system administrator to perform maintenance on a database without requiring a server shutdown or having to use the database ACL to restrict access.

In order to use markOutOfService(String, String) with a database on a clustered server, the remote Notes user must have at least designer access privileges.

If a user's privilege level is insufficient, a database access error is returned.
The markOutOfService(String, String) function affects only databases that reside on Domino clusters.
You can mark a database back in service by calling the markInService(String, String) function.

For more information, see the Domino Administration Help database.

Parameters:

server - db server

filePath - db filepath

sendConsoleCommand

String sendConsoleCommand(String server,
                          String command)

Sends a console command to a Domino server

Parameters:

server - server to contact, use "" for current server

command - command to execute

Returns:

response

generateSSOToken

ServerAdmin.DominoSSOToken generateSSOToken(String orgName,
                                            String configName,
                                            String userName,
                                            TemporalAccessor creationDate,
                                            TemporalAccessor expirationDate,
                                            boolean enableRenewal)

Generates a new SSO token on the current server

Parameters:

orgName - organization that the server belongs to, use null if not using Internet Site views for configuration

configName - name of Web SSO configuration to use

userName - Notes name to encode in the token, use either canonical or abbreviated format

creationDate - creation time to set for the token, use null for the current time

expirationDate - expiration time to set for the token, use null to use expiration from specified Web SSO configuration

enableRenewal - if true, the generated token contains the DominoDateTime where the token expires (for Domino only)

Returns:

token

getUserNamesList

UserNamesList getUserNamesList(String server,
                               String username)

Compute the name variants and groups of this user on the provided server. Does not contain roles as they are database-specific.

Parameters:

server - the server to query, use "" for current server

username - username

Returns:

a UserNamesList of user names that describe the user

computeDatabaseAccess

ServerAdmin.MultiDatabaseAccessInfo computeDatabaseAccess(String server,
                                                          UserNamesList user,
                                                          boolean forceNewScan)

Using this method you can efficiently scan a server directory and compute the AclAccess of users on the databases. While the first invocation may take a while to populate an internal cache of DB ACL copies, following calls should be pretty fast, because no databases have to be opened anymore. The cache is stored in the scope of this ServerAdmin object. So getting a new instance via DominoClient.getServerAdmin() requires rebuilding the cache.

Parameters:

server - the server to query, use "" for current server

user - UserNamesList of user to compute the effective database access level

forceNewScan - true to enforce a new directory scan (slow, I/O heavy); if false we return cached results on the second call

Returns:

ServerAdmin.MultiDatabaseAccessInfo providing access to database/access pairs

computeDatabaseAccess

ServerAdmin.MultiDatabaseAccessInfo computeDatabaseAccess(String server,
                                                          String username,
                                                          boolean forceNewScan)

Using this method you can efficiently scan a server directory and compute the AclAccess of users on the databases. While the first invocation may take a while to populate an internal cache of DB ACL copies, following calls should be pretty fast, because no databases have to be opened anymore. The cache is stored in the scope of this ServerAdmin object. So getting a new instance via DominoClient.getServerAdmin() requires rebuilding the cache.

Parameters:

server - the server to query, use "" for current server

username - username to compute the effective database access level

forceNewScan - true to enforce a new directory scan (slow, I/O heavy); if false we return cached results on the second call

Returns:

ServerAdmin.MultiDatabaseAccessInfo providing access to database/access pairs

getServerClusterMates

List<String> getServerClusterMates(String serverName,
                                   ServerAdmin.ClusterLookup lookupMode)

This function retrieves a list of server names that belong to the same cluster as the specified server.
If the serverName parameter is NULL then the function retrieves the cluster members of the user's home server.

The lookupMode parameter controls how the information is retrieved.
If the ServerAdmin.ClusterLookup.LOOKUP_NOCACHE flag is specified then the information is retrieved using a NameLookup on the server only.

If the ServerAdmin.ClusterLookup.LOOKUP_CACHEONLY flag is specified then the information is retrieved using the client's cluster name cache.

If no flag (a value of NULL) is specified, then the information is retrieved first through the client's cluster name cache and if that is not successful, then through a NameLookup on the server.
Note that the list returned does not include the input server name (or home server name if NULL was specified).

getServerClusterMates(String, ClusterLookup) uses the Address book specified by the user's location record.
Unless cascading Address books or Directory Assistance is enabled, the Notes mail domain field in the user's location record must be set to the domain name for the server(s) in the cluster and the Home/mail server field must be set to a server in this domain.

If the target server is in a different domain than specified in the user's location record then in order for getServerClusterMates(String, ClusterLookup) to succeed, you must have cascading Address books or Directory Assistance enabled and the target domain's Address book must be in the list of Address books to be searched.

Parameters:

serverName - The name of the Lotus Domino Server where the lookup will be performed (canonical or abbreviated format). Specify a value of NULL if the client's home server is to be used for the lookup.

lookupMode - lookup mode or null for "first local cache, then remote lookup"

Returns:

server list

registerCrossCertificate

void registerCrossCertificate(String certFilePath,
                              String certPW,
                              String certLogPath,
                              DominoDateTime expirationDateTime,
                              String regServer,
                              Path idFilePath,
                              String comment,
                              ServerAdmin.RegistrationMessageHandler msgHandler)

This function will cross-certify an ID with another organization's hierarchy.

It will open the Domino Directory (Server's Address book) on the specified registration server, verify write access to the book, and add a new Cross Certificate entry.

Parameters:

certFilePath - Pathname of the certifier id file

certPW - certifier password

certLogPath - Pathname of the certifier's log file. This parameter is required for Domino installations that use the Administration Process so that when using other C API function that require a Certifier Context, the proper entries will be entered in the Certification Log file (CERTLOG.NSF) . If your Domino installation does not include a Certification Log (does not use the Administration Process), then you should pass in NULL for this parameter.

expirationDateTime - certificate expiration date for the entity that is being certified

regServer - name of the Lotus Domino registration server containing the Domino Directory. The string should be no longer than MAXUSERNAME (256 bytes). If you want to specify "no server" (the local machine), pass "".

idFilePath - the pathname of the ID file to be cross-certified

comment - Any additional identifying information to be stored in the Domino Directory

msgHandler - optional callback to receive status messages or null

createServerStatusLine

ServerStatusLine createServerStatusLine(String taskName)

Creates a new status line for the given name.

This method only applies when running on a Domino server locally.

Parameters:

taskName - the name of the task to show in the line

Returns:

a newly-created status line object

Since:

1.0.11

openServerConsole

void openServerConsole(String serverName,
                       ServerAdmin.ConsoleHandler handler)

Opens a remote console for the specified server

Parameters:

serverName - server name (abbreviated or canonical format) or empty string for local server

handler - handler to receive the console messages

logMessage

void logMessage(String messageText)

Logs a message to the server using the Addin API.

Parameters:

messageText - the text to log to the server

Since:

1.0.20