oracle.ifs.core.runtime

Class Server

java.lang.Object

oracle.ifs.core.runtime.Server

All Implemented Interfaces:

ServerInterface

Direct Known Subclasses:

IfsServer

public abstract class Server
extends Object
implements ServerInterface

A Server is a managed CMSDK application.

Agents and protocol servers are two types of Server. An agent is an application that runs unattended and performs some operation, either periodically or in response to an IfsEvent. A protocol server opens a java.net.ServerSocket, awaits connections from clients, and performs operations dictated by a protocol specification in response to client requests.

To create a server, you can write a concrete subclass of this Server class. An easier approach, however, is to subclass IfsServer, which provides default implementations for methods, and provides tools for easily writing a thread-safe event-driven or timer-driven application.

Version:

1.0

Author:

David Pitfield, Dave Long

(Published)

Field Summary

Fields

Modifier and Type	Field and Description
static int	LEVEL_HIGH Deprecated. CM SDK 10g: Use IfsLogger for logging
static int	LEVEL_LOW Deprecated. CM SDK 10g: Use IfsLogger for logging
static int	LEVEL_MEDIUM Deprecated. CM SDK 10g: Use IfsLogger for logging
static int	LEVEL_OFF Deprecated. CM SDK 10g: Use IfsLogger for logging

Fields inherited from interface oracle.ifs.core.runtime.ServerInterface

SERVERSTATUS_DISPOSED, SERVERSTATUS_RUNNING, SERVERSTATUS_STARTING, SERVERSTATUS_STOPPED, SERVERSTATUS_STOPPING, SERVERSTATUS_SUSPENDED, SERVERSTATUS_UNKNOWN

Constructor Summary

Constructors

Constructor and Description
Server() Constructs a Server.

Method Summary

Modifier and Type	Method and Description
protected LibrarySession	acquireSession() Acquires a LibrarySession from the session pool.
protected LibrarySessionPool	constructLibrarySessionPool(int maxSessCount, String serviceName, String appName, SystemUserCredential cred) Constructs a LibrarySessionPool.
AttributeValue	createServerState() Creates a ServerState if it has not yet been created.
protected void	deregister() Deregisters this Server.
protected void	disconnectSession() Disconnects the Server's session.
AttributeValueTable	getConfigurationOverridesTable() Gets the configuration overrides specified for this Server.
AttributeValueTable	getConfigurationTable() Gets the effective configuration parameters for this Server, representing the combination of the initial Configuration and any overrides that have been applied.
Credential	getCredential(String name) Gets a Credential for the specified user.
int	getDesiredStatus() Gets the desired status of this Server.
String	getIfsHome() Gets the CM SDK home directory for this Server's node.
AttributeValueTable	getInitialConfigurationTable() Gets the initial configuration parameters for this Server as an AttributeValueTable.
IfsLogger	getLogger() Gets the appropriate logger for this server.
protected IfsLogger	getLoggerForLegacyLogging() Gets the IfsLogger to use for legacy logging.
String	getName() Gets the name of this Server.
protected NodeInterface	getNode() Gets the Node that manages this Server.
String	getNodeName() Gets the name of the node for this Server.
String	getOracleHome() Deprecated. 9.3.4.0: no longer a property that the Node makes available
ParameterTable	getParameterTable() Gets the configuration parameters for this Server as an immutable ParameterTable.
int	getPriority() Gets the priority of this Server.
AttributeValue[]	getProperties() Gets the values for all dynamic properties for this Server.
AttributeValue	getProperty(String name) Gets the value of the specified dynamic property for this Server.
String	getServerConfigurationName() Gets the server configuration name of this Server.
ServerState	getServerState(LibrarySession session) Gets the ServerState for this Server.
AttributeValue	getServerStateValue() Gets the ServerState value.
String	getServerType() Gets the type of this Server.
String	getServiceName() Gets the name of the default service for this Server.
protected LibrarySession	getSession() Gets the session for this Server.
AttributeValueTable	getStateTable() Gets the runtime state table.
int	getStatus() Gets the status of this Server.
SystemUserCredential	getSystemUserCredential() Gets a System user credential.
void	handleServerConfigurationOverrideRequest(ServerState ss) Handle ServerConfiguration overrides that have been posted.
protected void	handleServerStateEvent(String eventKey) Handle a ServerState event.
void	initialize() Initializes this Server.
void	initialize(String name, NodeInterface node, LibrarySessionPool sessionPool, AttributeValueTable initialConfig, AttributeValueTable overrides) Initializes this Server (managed by Node).
void	initialize(String name, String serviceName, String schemaPassword, ParameterTable parameterTable) Initializes this Server (standalone).
boolean	isAgent() Gets whether this Server is an agent.
protected boolean	isDisposed() Gets whether this Server has been disposed.
boolean	isInitialized() Gets whether this Server has been initialized and not disposed.
boolean	isLogged(int level) Deprecated. : Use IfsLogger for logging
void	log(int level, String message) Deprecated. : Use IfsLogger for logging
void	log(int level, String message, Throwable throwable) Deprecated. : Use IfsLogger for logging
void	log(int level, Throwable throwable) Deprecated. : Use IfsLogger for logging
protected void	releaseSession() Releases the Server's session back to the session pool.
protected void	releaseSession(LibrarySession session) Releases the specified session (that was previously acquired) back to the pool.
protected void	setDesiredStatus(int status) Sets the desired status of this Server.
protected void	setDesiredStatus(int status, boolean force) Sets the desired status of this Server.
void	setPriority(int priority) Sets the priority of this Server.
void	setSessionTimeoutPrevented(boolean prevented) Sets an indication as to whether or not sessions used by the Server should be prevented from timing out on long-running operations.
protected void	setStateProperty(AttributeValue av) Called when a dynamic (State) property of this Server is set or changed.
protected void	setStatus(int status) Sets the status of this Server.
void	startStandalone(String name, ParameterTable pt) Starts the server when run in standalone mode with the server properties specified as a ParameterTable.
void	startStandalone(String name, String[] args) Starts the server when run via a static main in standalone mode.
boolean	supportsPriority() Gets whether this Server supports set/get priority.
boolean	supportsSuspendResume() Gets whether this Server supports suspend/resume.
static String	toStatusLabel(int status) Gets a localized label for the specified status of a Server, using a default Localizer.
static String	toStatusLabel(int status, LibrarySessionInterface session) Gets a localized label for the specified status of a Server, using the specified session's Localizer.
static String	toStatusLabel(int serverStatus, Localizer localizer) Gets a localized label for the specified status of a Server, using the specified Localizer.
protected void	verifyNotDisposed() Verifies this Server has not been disposed.
protected void	verifyNotDisposed(int rethrowCode) Verifies this Server has not been disposed, and re-throws an IfsException of the specified code.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface oracle.ifs.core.runtime.ServerInterface

dispose, isPropertyReadonly, restart, resume, setProperty, start, stop, suspend

Field Detail

LEVEL_OFF

public static final int LEVEL_OFF

Deprecated. CM SDK 10g: Use IfsLogger for logging

Logging disabled.

See Also:

Constant Field Values

LEVEL_LOW

public static final int LEVEL_LOW

Deprecated. CM SDK 10g: Use IfsLogger for logging

Minimal logging.

See Also:

Constant Field Values

LEVEL_MEDIUM

public static final int LEVEL_MEDIUM

Deprecated. CM SDK 10g: Use IfsLogger for logging

Typical logging (the default).

See Also:

Constant Field Values

LEVEL_HIGH

public static final int LEVEL_HIGH

Deprecated. CM SDK 10g: Use IfsLogger for logging

Verbose logging.

See Also:

Constant Field Values

Constructor Detail

Server

public Server()
       throws IfsException

Constructs a Server.

Subclasses should provide a zero-argument constructor.

Throws:

IfsException - if the operation fails

(Published)

Method Detail

startStandalone

public void startStandalone(String name,
                            String[] args)
                     throws IfsException

Starts the server when run via a static main in standalone mode.

Parameters:

name - the name of the Server

args - the arguments supplied to the static main

Throws:

Exception - if the operation fails

IfsException

(Unpublished)

startStandalone

public void startStandalone(String name,
                            ParameterTable pt)
                     throws IfsException

Starts the server when run in standalone mode with the server properties specified as a ParameterTable.

Parameters:

name - the name of the Server

pt - the server properties

Throws:

IfsException - if the operation fails

(Unpublished)

initialize

public void initialize()
                throws Exception

Initializes this Server.

This method is called when the Server is first loaded. This method is typically implemented by each Server implementation.

Throws:

Exception - if the operation fails

(Published)

initialize

public void initialize(String name,
                       NodeInterface node,
                       LibrarySessionPool sessionPool,
                       AttributeValueTable initialConfig,
                       AttributeValueTable overrides)
                throws IfsException

Initializes this Server (managed by Node).

This method is called by Node in setting up Servers to be started.

Parameters:

name - the name of the Server

node - the managing Node context

sessionPool - the LibrarySession pool to use for session factory

initialConfig - the initial Server configuration parameters

overrides - the Server configuration parameter overrides

Throws:

IfsException - if the operation fails

(Published)

initialize

public void initialize(String name,
                       String serviceName,
                       String schemaPassword,
                       ParameterTable parameterTable)
                throws IfsException

Initializes this Server (standalone).

This method should be called when starting a Server outside the domain administration framework. For such a standalone Server, call this method immediately after the Server is constructed.

Parameters:

name - the name of the Server

serviceName - the name of the default service used by this Server; this service must be already started

schemaPassword - the schema password

parameterTable - the Server configuration parameters

Throws:

IfsException - (IFS-45201) if the operation fails

(Unpublished)

getServerStateValue

public AttributeValue getServerStateValue()
                                   throws IfsException

Gets the ServerState value.

Returns:

ServerState value, or null if no state exists yet

Throws:

IfsException - if the operation fails

(Published)

createServerState

public AttributeValue createServerState()
                                 throws IfsException

Creates a ServerState if it has not yet been created.

Returns:

the ServerState value

Throws:

IfsException - if the operation fails

(Published)

getServerState

public ServerState getServerState(LibrarySession session)
                           throws IfsException

Gets the ServerState for this Server.

Returns:

the ServerState associated with this Server

Throws:

IfsException - if the operation fails

getName

public String getName()
               throws IfsException

Gets the name of this Server.

Specified by:

getName in interface ServerInterface

Returns:

the name

Throws:

IfsException - (IFS-45160) if the operation fails

(Published)

getServerConfigurationName

public String getServerConfigurationName()
                                  throws IfsException

Gets the server configuration name of this Server.

Specified by:

getServerConfigurationName in interface ServerInterface

Returns:

the Server configuration name

Throws:

IfsException - (IFS-45179) if the operation fails

(Published)

getServiceName

public String getServiceName()
                      throws IfsException

Gets the name of the default service for this Server.

Specified by:

getServiceName in interface ServerInterface

Returns:

the service name

Throws:

IfsException - if the operation fails

(Published)

getServerType

public String getServerType()
                     throws IfsException

Gets the type of this Server.

Returns the fully-qualified classname of this Server.

Specified by:

getServerType in interface ServerInterface

Returns:

the server type

Throws:

IfsException - (IFS-45177) if the operation fails

(Published)

isAgent

public boolean isAgent()
                throws IfsException

Gets whether this Server is an agent.

Returns false by default.

Specified by:

isAgent in interface ServerInterface

Returns:

false

Throws:

IfsException - (IFS-45178) if the operation fails

(Published)

getStatus

public int getStatus()

Gets the status of this Server.

Specified by:

getStatus in interface ServerInterface

Returns:

the enumerated status

(Published)

getDesiredStatus

public int getDesiredStatus()

Gets the desired status of this Server.

Returns:

the enumerated status

(Published)

supportsSuspendResume

public boolean supportsSuspendResume()
                              throws IfsException

Gets whether this Server supports suspend/resume.

If false, then suspend and resume will result in stop and start instead.

Specified by:

supportsSuspendResume in interface ServerInterface

Returns:

false; subclasses may override

Throws:

IfsException - if the operation fails

(Published)

supportsPriority

public boolean supportsPriority()
                         throws IfsException

Gets whether this Server supports set/get priority.

If false, then setPriority and getPriority will throw an exception.

Specified by:

supportsPriority in interface ServerInterface

Returns:

true; to disable set/get priority, override this method

Throws:

IfsException - if the operation fails

(Published)

isInitialized

public boolean isInitialized()
                      throws IfsException

Gets whether this Server has been initialized and not disposed.

Returns:

true if the Server has been initialized and is not disposed

Throws:

IfsException - if the operation fails

(Published)

getParameterTable

public ParameterTable getParameterTable()
                                 throws IfsException

Gets the configuration parameters for this Server as an immutable ParameterTable.

These configuration parameters are provided by the Node in loading the Server, and are immutable.

Returns:

the Server configuration parameters

Throws:

IfsException - if the operation fails

(Published)

getInitialConfigurationTable

public AttributeValueTable getInitialConfigurationTable()
                                                 throws IfsException

Gets the initial configuration parameters for this Server as an AttributeValueTable.

The configuration parameters are provided by the Node in loading the Server, and are not subsequently updated.

Returns:

the initial Server configuration parameters

Throws:

IfsException - if the operation fails

(Published)

getConfigurationTable

public AttributeValueTable getConfigurationTable()
                                          throws IfsException

Gets the effective configuration parameters for this Server, representing the combination of the initial Configuration and any overrides that have been applied.

The configuration parameters are provided by the Node in loading the Server, and are updated whenever a Configuration Override is applied to the active Server.

Returns:

the Server configuration parameters

Throws:

IfsException - if the operation fails

(Published)

getConfigurationOverridesTable

public AttributeValueTable getConfigurationOverridesTable()
                                                   throws IfsException

Gets the configuration overrides specified for this Server.

The configuration overrides are provided by the Node in loading the Server, and are updated whenever a Configuration Override is applied to the active Server.

Returns:

the Server configuration parameter overrides

Throws:

IfsException - if the operation fails

(Published)

getStateTable

public AttributeValueTable getStateTable()
                                  throws IfsException

Gets the runtime state table.

Returns:

the Server runtime state table

Throws:

IfsException - if the operation fails

(Published)

getNode

protected NodeInterface getNode()
                         throws IfsException

Gets the Node that manages this Server.

Returns:

the managing Node, or null if the Server is unmanaged

Throws:

IfsException - if the operation fails

(Published)

getNodeName

public String getNodeName()
                   throws IfsException

Gets the name of the node for this Server.

Returns:

the node name

Throws:

IfsException - if the operation fails

(Published)

getOracleHome

public String getOracleHome()
                     throws IfsException

Deprecated. 9.3.4.0: no longer a property that the Node makes available

Gets the Oracle home directory for this Server's node.

The Oracle home directory is specified by the Server's IFS.SERVER.OracleHome parameter.

Returns:

the Oracle home directory

Throws:

IfsException - (IFS-45208) if the operation fails

(Published)

getIfsHome

public String getIfsHome()
                  throws IfsException

Gets the CM SDK home directory for this Server's node.

The CM SDK home directory is specified by the node's IFS.NODE.IfsHome parameter. (For standalone Servers, the CM SDK home directory is specified by the server's parameter named IFS.NODE.IfsHome.)

Returns:

the CM SDK home directory

Throws:

IfsException - (IFS-45207) if the operation fails

(Unpublished)

getLogger

public IfsLogger getLogger()

Gets the appropriate logger for this server.

Typically overridden by subclasses to return the IfsLogger associatged with the specific server.

Returns:

the logger

(Published)

acquireSession

protected LibrarySession acquireSession()
                                 throws IfsException

Acquires a LibrarySession from the session pool.

Returns:

the acquired session

Throws:

IfsException - if the operation fails

(Published)

getSession

protected LibrarySession getSession()

Gets the session for this Server.

Returns:

the Server's session

(Published)

releaseSession

protected void releaseSession()
                       throws IfsException

Releases the Server's session back to the session pool.

Throws:

IfsException - if the operation fails

(Published)

releaseSession

protected void releaseSession(LibrarySession session)
                       throws IfsException

Releases the specified session (that was previously acquired) back to the pool.

Parameters:

session - the session

Throws:

IfsException - if the operation fails

(Published)

disconnectSession

protected void disconnectSession()
                          throws IfsException

Disconnects the Server's session.

If there is no Server session, no action is taken. Any exception that occurs in disconnecting the session is consumed.

Throws:

IfsException - if the operation fails

(Published)

setSessionTimeoutPrevented

public void setSessionTimeoutPrevented(boolean prevented)
                                throws IfsException

Sets an indication as to whether or not sessions used by the Server should be prevented from timing out on long-running operations.

If set to true, then all new LibrarySessions created as a result of getSession or acquireSession calls will not incur session timeouts due to long-running operations. If this option is changed after obtaining a session, the current session is not changed.

It is best to invoke this method during initialize so that all sessions created subsequently have the desired behavior with respect to session timeouts.

Parameters:

prevented - true if session timeouts are to be prevented.

Throws:

IfsException - if the operation fails

(Published)

getSystemUserCredential

public SystemUserCredential getSystemUserCredential()
                                             throws IfsException

Gets a System user credential.

Returns:

a SystemUserCredential

Throws:

IfsException - if the operation fails

(Published)

constructLibrarySessionPool

protected LibrarySessionPool constructLibrarySessionPool(int maxSessCount,
                                                         String serviceName,
                                                         String appName,
                                                         SystemUserCredential cred)
                                                  throws IfsException

Constructs a LibrarySessionPool.

Parameters:

maxSessCount - the maximum number of sessions that can be constructed by this pool

serviceName - the service name

appName - the application name (for DB connection metadata)

cred - the system user credentials

Throws:

IfsException - if the operation fails

(Published)

getCredential

public Credential getCredential(String name)
                         throws IfsException

Gets a Credential for the specified user.

A TokenCredential is returned. In this way, this Server can obtain a valid Credential for any CM SDK user without that user's password.

The generated TokenCredential is valid for one use or 600 seconds, whichever comes first.

Parameters:

name - the user name

Returns:

the Credential

Throws:

IfsException - (IFS-45206) if the operation fails

(Published)

getProperty

public AttributeValue getProperty(String name)
                           throws IfsException

Gets the value of the specified dynamic property for this Server.

Specified by:

getProperty in interface ServerInterface

Parameters:

name - the property name

Returns:

the property value, or null if no such property

Throws:

IfsException - (IFS-45172) if the operation fails

(Published)

getProperties

public AttributeValue[] getProperties()
                               throws IfsException

Gets the values for all dynamic properties for this Server.

Specified by:

getProperties in interface ServerInterface

Returns:

the property values, or null if there are no dynamic properties for this Server

Throws:

IfsException - (IFS-45173) if the operation fails

(Published)

setStateProperty

protected void setStateProperty(AttributeValue av)
                         throws IfsException

Called when a dynamic (State) property of this Server is set or changed.

Parameters:

av - the property (name and value assumed to be set)

Throws:

IfsException - if the operation fails

(Published)

handleServerStateEvent

protected void handleServerStateEvent(String eventKey)
                               throws IfsException

Handle a ServerState event.

Parameters:

eventKey - the ServerState event key

Throws:

IfsException - if the operation fails

handleServerConfigurationOverrideRequest

public void handleServerConfigurationOverrideRequest(ServerState ss)
                                              throws IfsException

Handle ServerConfiguration overrides that have been posted.

Parameters:

ss - the ServerState instance

Throws:

IfsException - if the operation fails

setDesiredStatus

protected void setDesiredStatus(int status)
                         throws IfsException

Sets the desired status of this Server.

Parameters:

status - the new status

Throws:

IfsException - if the operation fails

(Published)

setDesiredStatus

protected void setDesiredStatus(int status,
                                boolean force)
                         throws IfsException

Sets the desired status of this Server.

Parameters:

status - the new status

force - if true, set the desired status regardless of the current status

Throws:

IfsException - if the operation fails

(Published)

setStatus

protected void setStatus(int status)
                  throws IfsException

Sets the status of this Server.

Parameters:

status - the new status

Throws:

IfsException - if the operation fails

(Published)

deregister

protected void deregister()
                   throws IfsException

Deregisters this Server.

This method called after the Server is disposed, so that it can notify its managing Node (if any) that it is disposed.

Throws:

IfsException - (IFS-45205) if the operation fails

(Published)

getPriority

public int getPriority()
                throws IfsException

Gets the priority of this Server.

Specified by:

getPriority in interface ServerInterface

Returns:

the priority

Throws:

IfsException - if the operation fails

(Published)

setPriority

public void setPriority(int priority)
                 throws IfsException

Sets the priority of this Server.

Specified by:

setPriority in interface ServerInterface

Parameters:

priority - the priority

Throws:

IfsException - if the operation fails

(Published)

toStatusLabel

public static String toStatusLabel(int status)
                            throws IfsException

Gets a localized label for the specified status of a Server, using a default Localizer.

Equivalent to toStatusLabel(status, null).

Parameters:

status - the status

Returns:

the label

Throws:

IfsException - if the operation fails

(Published)

toStatusLabel

public static String toStatusLabel(int status,
                                   LibrarySessionInterface session)
                            throws IfsException

Gets a localized label for the specified status of a Server, using the specified session's Localizer.

Equivalent to toStatusLabel(status, session.getLocalizer()).

Parameters:

status - the status

session - the session

Returns:

the label

Throws:

IfsException - if the operation fails

(Published)

toStatusLabel

public static String toStatusLabel(int serverStatus,
                                   Localizer localizer)
                            throws IfsException

Gets a localized label for the specified status of a Server, using the specified Localizer.

If localizer is null, this method is equivalent to toStatusLabel(status, new Localizer()).

Parameters:

serverStatus - the status

localizer - the Localizer

Returns:

the label

Throws:

IfsException - if the operation fails

(Published)

isDisposed

protected boolean isDisposed()
                      throws IfsException

Gets whether this Server has been disposed.

Returns:

true if this Server has been disposed

Throws:

IfsException - if this Server has been disposed

(Published)

verifyNotDisposed

protected final void verifyNotDisposed()
                                throws IfsException

Verifies this Server has not been disposed.

The getStatus method is called to check the status of this Server.

Invoking methods on a disposed Server (other than getStatus, getName and deregister) is illegal and should throw an exception. Call this method to perform that check.

Throws:

IfsException - (IFS-45203) if this Server has been disposed

(Published)

verifyNotDisposed

protected final void verifyNotDisposed(int rethrowCode)
                                throws IfsException

Verifies this Server has not been disposed, and re-throws an IfsException of the specified code.

Throws:

IfsException - if this Server has been disposed

(Published)

getLoggerForLegacyLogging

protected IfsLogger getLoggerForLegacyLogging()

Gets the IfsLogger to use for legacy logging.

Returns:

the logger to use for legacy logging

log

public void log(int level,
                String message)

Deprecated. : Use IfsLogger for logging

Logs the specified message.

Parameters:

level - the minimum logging level for the message

message - the message

log

public void log(int level,
                Throwable throwable)

Deprecated. : Use IfsLogger for logging

Logs the specified throwable.

Parameters:

level - the minimum logging level for the message

throwable - the throwable

log

public void log(int level,
                String message,
                Throwable throwable)

Deprecated. : Use IfsLogger for logging

Logs the specified message and throwable, as a single log entry.

Parameters:

level - the minimum logging level for the message

message - the message

throwable - the throwable

isLogged

public boolean isLogged(int level)

Deprecated. : Use IfsLogger for logging

Gets whether calling log with the specified logging level would cause a message to be logged.

Parameters:

level - the logging level

Returns:

whether a message would be logged