oracle.ifs.management.domain
Class IfsServer

java.lang.Object
  |
  +--oracle.ifs.management.domain.Server
        |
        +--oracle.ifs.management.domain.IfsServer

All Implemented Interfaces:

ServerInterface

public abstract class IfsServer

extends Server

IfsServer is an abstract base class for iFS servers.

Subclassing IfsServer provides an easier approach to creating a server than subclassing Server itself. IfsServer provides default implementations for many of the methods required, offers a set of tools useful in writing a server, and simplifies development of a thread-safe server.

The most basic server can be created by subclassing IfsServer, providing a zero-argument constructor, and implementing the run method.

More sophisticated servers provide implementations for the following life-cycle methods:

• initialize: operations performed once, when the server is loaded on the node
• preRun: operations performed each time the server is started, immediately before run is called
• run: operations performed when the server is running
• postRun: operations performed each time the server is stopped, immediately after run returns
• dispose: operations performed once, when the server is unloaded from the node

Servers can obtain information on their runtime environment by calling the following methods:

• getName: gets the name of the server
• getParameterTable: gets the configuration parameters for the server
• getServiceName and getService: gets the service against which the server should operate
• getStatus: gets the current server state
• stopRequested: gets whether the server should stop

A server can publish dynamic properties regarding its operation (for example, the current number of connections). These properties can be readonly (viewed using iFS Manager) or writeable (viewed and set using iFS Manager).

A timer can be started to generate periodic "timer expiration" requests. This is useful for servers that perform some task at defined intervals.

A server can establish a "default" LibrarySession against which it operates. If a server uses more than one LibrarySession, it can call getCredential to obtain a credential for any iFS user.

A typical server may respond to administrative commands (such as "stop"), iFS events, and expirations of its timer. To simplify thread-safety, IfsServer allows these stimuli to be enqueued when received, for subsequent processing by a single thread. To do this, the run method has a canonical dispatch loop to dequeue and handle such stimuli by calling the following methods, implemented by the IfsServer subclass:

• handleTimerExpired: when the IfsServer timer expires
• handleStopRequest: when stop is called to request the server to stop
• handleSuspendRequest: when suspend is called to request the server to suspend
• handleResumeRequest: when resume is called to request the server to resume
• handlePriorityChangeRequest: when setPriority is called to change the server's priority
• handlePropertyChangeRequest: when setProperty is called to change a dynamic property of the server
• processEvent: to process an event received

Servers should operate against services already running on the node. A server should not start its own service.

A server can write to its node's log by calling log.

For testing purposes, a server can be run "standalone", not on a node. To do this, the server should provide a static main method that obtains a ParameterTable, starts a service, constructs the server, calls the six-argument initialize method, and finally calls start to run the server.

Fields inherited from class oracle.ifs.management.domain.Server

LEVEL_HIGH, LEVEL_LOW, LEVEL_MEDIUM, LEVEL_OFF

Fields inherited from interface oracle.ifs.management.domain.ServerInterface

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

Constructor Summary

IfsServer()
Constructs an IfsServer.

Method Summary

protected LibrarySession	checkSession() Gets the default session for this Server, performing additional checks to ensure the session is still connected and valid.
protected LibrarySession	connectSession() Gets a default LibrarySession for this Server.
protected void	disconnectSession() Disconnects the default session for this Server.
void	dispose() Disposes this Server.
protected java.util.Date	getLastTimerActivation() Gets the time at which the timer last generated a "timer expiration" request for this Server.
protected java.util.Date	getNextTimerActivation() Gets the time at which the timer will next generate a "timer expiration" request for this Server.
int	getPriority() Gets the priority of this Server.
AttributeValue[]	getProperties() Gets the values for all dynamic properties for this Server.
AttributeValue	getProperty(java.lang.String name) Gets the value of the specified dynamic property for this Server.
java.lang.String	getServerType() Gets the type of this Server.
protected LibraryService	getService() Gets the default service for this Server.
protected LibrarySession	getSession() Gets the default session for this Server.
int	getStatus() Gets the status of this Server.
protected void	handlePriorityChangeRequest() Called when this Server's priority is changed.
protected void	handlePropertyChangeRequest(AttributeValue av) Called when a dynamic property of this Server is set or changed.
protected void	handleRequests() Dispatches any pending requests for this Server.
protected void	handleResumeRequest() Called when this Server is requested to resume.
protected void	handleStopRequest() Called when this Server is requested to stop.
protected void	handleSuspendRequest() Called when this Server is requested to suspend.
protected void	handleTimerExpired() Called when the Server's timer expires.
boolean	isAgent() Gets whether this Server is an agent.
boolean	isPropertyReadonly(java.lang.String name) Gets whether the specified dynamic property is readonly.
protected boolean	isTimerActive() Gets whether the timer for this Server is started.
protected void	postRun() The post-run tasks for this Server.
protected void	preRun() The pre-run tasks for this Server.
protected void	processEvent(IfsEvent event) Processes an IfsEvent previously placed in this Server's event queue by queueEvent.
protected void	processEvents() Dispatches any IfsEvents previously placed in this Server's event queue by queueEvent.
protected void	queueEvent(IfsEvent event) Queues an IfsEvent for this Server.
protected void	resetTimer() Resets the timer for this Server.
void	restart() Requests this Server to restart.
void	resume() Requests this Server to resume.
protected abstract void	run() The run tasks for this Server.
void	setPriority(int priority) Sets the priority of this Server.
void	setProperty(AttributeValue av) Sets the value of the specified dynamic property for this Server.
void	setProperty(java.lang.String name, AttributeValue av) Sets the value of the specified dynamic property for this Server.
void	start() Requests this Server to start.
protected void	startTimer() Starts a timer that will generate "timer expiration" requests for this Server at a specified interval.
void	stop() Requests this Server to stop.
protected boolean	stopRequested() Indicates this Server should stop.
protected void	stopTimer() Stops the timer for this Server.
boolean	supportsPriority() Gets whether this Server supports set/get priority.
boolean	supportsSuspendResume() Gets whether this Server supports suspend/resume.
void	suspend() Requests this Server to suspend.
protected void	waitServer() Blocks the current thread until one of the following occurs.

Methods inherited from class oracle.ifs.management.domain.Server

deregister, getCredential, getName, getNodeName, getOracleHome, getParameterTable, getServiceName, initialize, initialize, isLogged, log, log, log, toStatusLabel, toStatusLabel, toStatusLabel, verifyNotDisposed

Constructor Detail

IfsServer

public IfsServer()
          throws IfsException

Constructs an IfsServer.

Subclasses should provide a zero-argument constructor.

Throws:

IfsException - if the operation fails

Method Detail

getServerType

public java.lang.String getServerType()
                               throws IfsException

Gets the type of this Server.

Server type is used by iFS administration tools to aggregate data from servers of the same type in administration user interfaces. By default, IfsServer returns the fully-qualified classname of this Server.

Returns:

the server type

Throws:

IfsException - (IFS-45177) if the operation fails

isAgent

public boolean isAgent()
                throws IfsException

Gets whether this Server is an agent.

This method is called by iFS administration tools to group together servers that are agents in administration user interfaces. IfsServer returns false by default.

Returns:

false

Throws:

IfsException - (IFS-45178) if the operation fails

getStatus

public final int getStatus()
                    throws IfsException

Gets the status of this Server.

Returns:

the enumerated status

Throws:

IfsException - (IFS-45161) if the operation fails

supportsSuspendResume

public boolean supportsSuspendResume()
                              throws IfsException

Gets whether this Server supports suspend/resume.

If false, then suspend and resume will throw an exception.

Returns:

false; to support suspend/resume, override this method, handleSuspendRequest, and handleResumeRequest

Throws:

IfsException - (IFS-45162) if the operation fails

supportsPriority

public boolean supportsPriority()
                         throws IfsException

Gets whether this Server supports set/get priority.

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

Returns:

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

Throws:

IfsException - (IFS-45163) if the operation fails

start

public final void start()
                 throws IfsException

Requests this Server to start.

Throws:

IfsException - (IFS-45164) if the operation fails

stop

public final void stop()
                throws IfsException

Requests this Server to stop.

Throws:

IfsException - (IFS-45165) if the operation fails

restart

public final void restart()
                   throws IfsException

Requests this Server to restart.

Restart is equivalent to a stop followed by a start.

Throws:

IfsException - (IFS-45166) if the operation fails

suspend

public final void suspend()
                   throws IfsException

Requests this Server to suspend.

Throws:

IfsException - (IFS-45167) if the operation fails

resume

public final void resume()
                  throws IfsException

Requests this Server to resume.

Throws:

IfsException - (IFS-45168) if the operation fails

dispose

public void dispose()
             throws IfsException

Disposes this Server.

This deregisters the Server to unload it from the iFS node. The Server must already be stopped.

Subclasses that override this method should call super.dispose() unless they intend to veto the dispose request.

Throws:

IfsException - (IFS-45169) if the operation fails

getPriority

public int getPriority()
                throws IfsException

Gets the priority of this Server.

The priority must be between Thread.MIN_PRIORITY and Thread.MAX_PRIORITY, inclusive.

Returns:

the priority

Throws:

IfsException - (IFS-45170) if the operation fails

setPriority

public void setPriority(int priority)
                 throws IfsException

Sets the priority of this Server.

The priority must be between Thread.MIN_PRIORITY and Thread.MAX_PRIORITY, inclusive.

If this Server is starting, running, or suspended, this method will post a priority change request, which will trigger a call to handlePriorityChangeRequest when the canonical dispatch loop of run calls handleRequests. However, if this Server is stopped, this method will instead synchronously invoke handlePriorityChangeRequest in the invoking thread. Finally, if the Server is stopping or disposed, this method will throw an exception indicating this.

Parameters:

priority - the priority

Throws:

IfsException - (IFS-45171) if the operation fails

getProperty

public AttributeValue getProperty(java.lang.String name)
                           throws IfsException

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

Parameters:

name - the property name

Returns:

the property value, or null if there is no such property

Throws:

IfsException - (IFS-45172) if the operation fails

getProperties

public AttributeValue[] getProperties()
                               throws IfsException

Gets the values for all dynamic properties for this Server.

Returns:

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

Throws:

IfsException - (IFS-45173) if the operation fails

setProperty

public void setProperty(AttributeValue av)
                 throws IfsException

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

If this Server is starting, running, or suspended, this method will post a property change request, which will trigger a call to handlePropertyChangeRequest when the canonical dispatch loop of run calls handleRequests. However, if this Server is stopped, this method will instead synchronously invoke handlePropertyChangeRequest in the invoking thread. Finally, if the Server is stopping or disposed, this method will throw an exception indicating this.

Parameters:

av - the property; the name of the AttributeValue must be set and is the property name

Throws:

IfsException - (IFS-45174) if the operation fails

setProperty

public void setProperty(java.lang.String name,
                        AttributeValue av)
                 throws IfsException

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

If this Server is starting, running, or suspended, this method will post a property change request, which will trigger a call to handlePropertyChangeRequest when the canonical dispatch loop of run calls handleRequests. However, if this Server is stopped, this method will instead synchronously invoke handlePropertyChangeRequest in the invoking thread. Finally, if the Server is stopping or disposed, this method will throw an exception indicating this.

Parameters:

name - the property name

av - the property value

Throws:

IfsException - (IFS-45174) if the operation fails

isPropertyReadonly

public boolean isPropertyReadonly(java.lang.String name)
                           throws IfsException

Gets whether the specified dynamic property is readonly.

Readonly properties cannot be set using setProperty.

Parameters:

name - the property name

Returns:

true; override this method to allow properties to be set using setProperty

Throws:

IfsException - (IFS-45176) if the operation fails

getService

protected final LibraryService getService()
                                   throws IfsException

Gets the default service for this Server.

Equivalent to LibraryService.findService(getServiceName()).

Returns:

the default service

Throws:

IfsException - (IFS-45373) if the operation fails

connectSession

protected final LibrarySession connectSession()
                                       throws IfsException

Gets a default LibrarySession for this Server.

If this Server already has a default LibrarySession (because this method was previously invoked) it is returned. Otherwise, a new session is connected based on the following server configuration parameters:

• IFS.SERVER.SESSION.User: the user name; required
• IFS.SERVER.SESSION.ApplicationName: the ConnectOptions' application name; optional; defaults to the name of this Server
• IFS.SERVER.SESSION.LOCALE.Language: the ConnectOptions locale language; optional
• IFS.SERVER.SESSION.LOCALE.Country: the ConnectOptions locale country; optional
• IFS.SERVER.SESSION.LOCALE.Variant: the ConnectOptions locale variant; optional

  Returns:

  the default session

  Throws:

  IfsException - (IFS-45360) if the operation fails

disconnectSession

protected final void disconnectSession()
                                throws IfsException

Disconnects the default session for this Server.

If there is no default session, no action is taken.

Throws:

IfsException - (IFS-45361) if the operation fails

getSession

protected final LibrarySession getSession()

Gets the default session for this Server.

Returns:

the default session, or null if there is no default session for this Server

checkSession

protected final LibrarySession checkSession()
                                     throws IfsException

Gets the default session for this Server, performing additional checks to ensure the session is still connected and valid.

Returns:

the default session, or null if there is no default session for this Server of if the default session has no longer viable

Throws:

IfsException - (IFS-45363) if the operation fails

preRun

protected void preRun()
               throws java.lang.Exception

The pre-run tasks for this Server.

This method is invoked each time this Server is started. Unless overridden, no operation is performed by this method. The Server status is SERVERSTATUS_STARTING while this method executes. When this method returns, the status changes to SERVERSTATUS_RUNNING and run is invoked. However, if this method throws, the status is set to SERVERSTATUS_STOPPING and postRun is invoked.

Throws:

java.lang.Exception - if the operation fails

run

protected abstract void run()

The run tasks for this Server.

Override this method with tasks to be performed by this Server. This method is called after preRun each time this Server is started. The server status is SERVERSTATUS_RUNNING while this method executes. When this method terminates (by returning or throwing), the status is set to SERVERSTATUS_STOPPING and postRun is invoked.

The run method should provide a loop to dispatch requests and events. The canonical form of this loop is:

 while (!stopRequested())
 {
     try
     {
         handleRequests();
         processEvents();
         waitServer();
     }
     catch (Exception e)
     {
         log(LEVEL_LOW, e);
     }
 }
 

postRun

protected void postRun()

The post-run tasks for this Server.

This method is invoked each time this Server is stopped, whether by the run method returning or either the preRun or run methods throwing. Unless overridden, no operation is performed by this method. While this method executes, the server status is SERVERSTATUS_STOPPING. When this method terminates (by either returning or throwing), the status of the server is set to SERVERSTATUS_STOPPED.

stopRequested

protected boolean stopRequested()

Indicates this Server should stop.

This method is invoked by the canonical dispatch loop of the run method. The default implementation of handleStopRequest causes subsequent calls to this method to return true.

Returns:

whether this Server should stop

startTimer

protected final void startTimer()
                         throws IfsException

Starts a timer that will generate "timer expiration" requests for this Server at a specified interval.

The timer behavior is governed by a set of server configuration parameters:

• IFS.SERVER.TIMER.ActivationPeriod: The frequency of timer events. Must be specified for the timer to be activated. The value is an integer, followed by an optional unit ("H" for hours, "M" for minutes, "S" for seconds; if no unit is specified, milliseconds is used). Examples:
  • IFS.SERVER.TIMER.ActivationPeriod = 4h (every 4 hours)
  • IFS.SERVER.TIMER.ActivationPeriod = 90m (every 90 minutes)
  • IFS.SERVER.TIMER.ActivationPeriod = 3500 (every 3.5 seconds)
• IFS.SERVER.TIMER.InitialTimeOfDay: The time of day for the first timer expiration. If omitted, the time of the first timer expiration is instead determined by the IFS.SERVER.TIMER.InitialDelay parameter. The value is specified as "HH:mm:ss". Examples:
  • IFS.SERVER.TIMER.InitialTimeOfDay = 3:30:00 (for 3:30 a.m.)
  • IFS.SERVER.TIMER.InitialTimeOfDay = 20:00:00 (for 8:00 p.m.)
• IFS.SERVER.TIMER.InitialDelay: The delay before the first timer expiration, relative to when the Server is started. If both IFS.SERVER.TIMER.InitialDelay and IFS.SERVER.TIMER.InitialTimeOfDay are omitted, the initial delay defaults to IFS.SERVER.TIMER.ActivationPeriod. Has the same format as IFS.SERVER.TIMER.ActivationPeriod. Examples:
  • IFS.SERVER.TIMER.InitialDelay = 30m (30 minute delay)
  • IFS.SERVER.TIMER.InitialDelay = 90s (90 second delay)

If the timer is already started, it is stopped and restarted.

Throws:

IfsException - (IFS-45364) if the operation fails

stopTimer

protected final void stopTimer()
                        throws IfsException

Stops the timer for this Server.

If the timer is not started, this method has no effect.

Throws:

IfsException - (IFS-45365) if the operation fails

resetTimer

protected final void resetTimer()
                         throws IfsException

Resets the timer for this Server.

This has the effect of preventing the next "timer expired" event from occurring until the Activation Period elapses relative to the current time. If the timer is not started, this method has no effect.

Throws:

IfsException - (IFS-45374) if the operation fails

isTimerActive

protected final boolean isTimerActive()
                               throws IfsException

Gets whether the timer for this Server is started.

Returns:

whether the timer is started

Throws:

IfsException - (IFS-45366) if the operation fails

getLastTimerActivation

protected final java.util.Date getLastTimerActivation()
                                               throws IfsException

Gets the time at which the timer last generated a "timer expiration" request for this Server.

Returns:

the time, or null if either the timer is stopped or has not yet generated a timed expiration request

Throws:

IfsException - (IFS-45367) if the operation fails

getNextTimerActivation

protected final java.util.Date getNextTimerActivation()
                                               throws IfsException

Gets the time at which the timer will next generate a "timer expiration" request for this Server.

Returns:

the time, or null if the timer is stopped

Throws:

IfsException - (IFS-45368) if the operation fails

queueEvent

protected final void queueEvent(IfsEvent event)
                         throws IfsException

Queues an IfsEvent for this Server.

This method is typically called by the handleEvent method of an IfsEventHandler. The event remains in the Server's event queue until processEvents is called by the Server's run method, at which point processEvent is called to dispatch the event.

Throws:

IfsException - (IFS-45369) if the operation fails

handleRequests

protected final void handleRequests()
                             throws IfsException

Dispatches any pending requests for this Server.

This method is invoked by the canonical dispatch loop of the run method. It results in calls to handleTimerExpired, handleStopRequest, handleSuspendRequest, handleResumeRequest, handlePriorityChangeRequest, and handlePropertyChangeRequest. These calls occur in the same thread that called this method. Should one of these methods throw, request handling will cease, any requests not yet dispatched will remain pending, and this method will rethrow the exception.

Throws:

IfsException - (IFS-45370) if the operation fails

processEvents

protected final void processEvents()
                            throws IfsException

Dispatches any IfsEvents previously placed in this Server's event queue by queueEvent.

This method is invoked by the canonical dispatch loop of the run method. It results in calls to the method processEvent. These calls occur in the same thread that called this method. Should one of these calls throw, event dispatching will cease, any events not yet dispatched will remain in this Server's event queue, and this method will rethrow the exception.

Throws:

IfsException - (IFS-45371) if the operation fails

waitServer

protected final void waitServer()
                         throws IfsException

Blocks the current thread until one of the following occurs.

• the Server's timer expires
• the Server is requested to stop
• the Server is requested to suspend
• the Server is requested to resume
• the Server's priority is changed
• the dynamic property of the Server is changed
• queueEvent is called to enqueue an event

This method is invoked by the canonical dispatch loop of the run method.

Throws:

IfsException - (IFS-45372) if the operation fails

handleTimerExpired

protected void handleTimerExpired()
                           throws java.lang.Exception

Called when the Server's timer expires.

This method is called by handleRequests. Override it to perform tasks when the timer expires. Unless overridden, no operation is performed by this method.

The handleRequests method will rethrow any exception thrown by this method.

Throws:

java.lang.Exception - if the operation fails

handleStopRequest

protected void handleStopRequest()
                          throws java.lang.Exception

Called when this Server is requested to stop.

This method is called by handleRequests. Override it to perform tasks upon a request to stop. If not overridden, this method simply causes subsequent calls to stopRequested to return true.

The handleRequests method will rethrow any exception thrown by this method.

Throws:

java.lang.Exception - if the operation fails

handleSuspendRequest

protected void handleSuspendRequest()
                             throws java.lang.Exception

Called when this Server is requested to suspend.

This method is called by handleRequests. Override it to perform tasks upon a suspend request. Unless overridden, no operation is performed by this method.

If this method returns without throwing, the Server's status is set to SERVERSTATUS_SUSPENDED.

The handleRequests method will rethrow any exception thrown by this method.

Throws:

java.lang.Exception - if the operation fails

handleResumeRequest

protected void handleResumeRequest()
                            throws java.lang.Exception

Called when this Server is requested to resume.

This method is called by handleRequests. Override it to perform tasks upon a resume request. Unless overridden, no operation is performed by this method.

If this method returns without throwing, the Server's status is set to SERVERSTATUS_RUNNING.

The handleRequests method will rethrow any exception thrown by this method.

Throws:

java.lang.Exception - if the operation fails

handlePriorityChangeRequest

protected void handlePriorityChangeRequest()
                                    throws java.lang.Exception

Called when this Server's priority is changed.

This method is called by handleRequests. Override it to perform tasks upon a priority change. To obtain the new priority, call getPriority. If not overridden, this method simply changes the priority of the current thread.

The handleRequests method will rethrow any exception thrown by this method.

Throws:

java.lang.Exception - if the operation fails

handlePropertyChangeRequest

protected void handlePropertyChangeRequest(AttributeValue av)
                                    throws java.lang.Exception

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

This method is called by handleRequests. Override it to perform tasks when a dynamic property is set or changed. If not overridden, this method simply causes the requested property to be changed.

The handleRequests method will rethrow any exception thrown by this method.

A Server may also call this method to set the value of a dynamic property. Unlike calling setProperty, calling this method sets the property's value synchronously, and also allows the value of a readonly property to be set.

Parameters:

av - the property

Throws:

java.lang.Exception - if the operation fails

processEvent

protected void processEvent(IfsEvent event)
                     throws java.lang.Exception

Processes an IfsEvent previously placed in this Server's event queue by queueEvent.

This method is called by processEvents. Override it to perform tasks in response to an event. Unless overridden, no operation is performed by this method.

The processEvents method will rethrow any exception thrown by this method.

Parameters:

event - the event

Throws:

java.lang.Exception - if the operation fails