Context Interface

weblogic.jws.control
Context Interface

public interface Context

    extends Serializable

Provides access to services and information specific to this component's context. You will never need to extend or implement this interface. You will use this interface only through more specific subinterfaces, such as JwsContext and ControlContext.


All Superinterfaces
Serializable
All Known Subinterfaces

ControlContext, JwsContext, JwsContext

Nested Class Summary

public static interfaceContext.Callback
           Defines callback events that may be received by the container.

Method Summary

public void
finishConversation()
Marks the current conversation instance as requiring removal after the currently executing method or event handler returns.
public Principal
getCallerPrincipal()
Returns the security principal associated with the current method invocation if authentication was performed.
public long
getCurrentAge()
Returns the conversation's current age (in seconds).
public long
getCurrentIdleTime()
Gets the number of seconds since the last client request, or since the conversation's maximum idle time was reset.
public Logger
getLogger(String name)
Gets an instance of the Logger class, which you can use to send messages from your code to a log file.
public long
getMaxAge()
Gets the time representing the longest the conversation may remain active before finishing.
public long
getMaxIdleTime()
Gets the number of seconds that the conversation can remain idle before finishing due to client inactivity.
public ServiceHandle
getService()
Returns a ServiceHandle instance for the currently active service instance.
public boolean
isCallerInRole(String roleName)
Returns true if the authenticated principal is within the specified security role.
public boolean
isFinished()
Returns whether or not this conversation instance has had finish() called on it (indicating that code has requested termination of this conversation instance).
public void
resetIdleTime()
Resets the timer measuring the number of seconds since the last activity for the current conversation.
public void
setMaxAge(Date date)
Sets a new maximum age for the conversation to an absolute Date.
public void
setMaxAge(String duration)
Sets a conversation's maximum age by specifying a duration as a string.
public void
setMaxIdleTime(long seconds)
Sets the number of seconds that the conversation can remain idle before finishing due to client inactivity.
public void
setMaxIdleTime(String duration)
Sets the number of seconds (as a String) that the conversation can remain idle before finishing due to client inactivity.

Method Detail

finishConversation() Method

public void finishConversation()
Marks the current conversation instance as requiring removal after the currently executing method or event handler returns.

Call this method to force removal of the conversation instance as an alternative to waiting for it to be removed by WebLogic Server when the conversation times out or its "finish" method is reached. Calling this method from within another method is equivalent to marking the calling method with the @conversation phase="finish" tag.


getCallerPrincipal() Method

public Principal getCallerPrincipal()
Returns the security principal associated with the current method invocation if authentication was performed.

Returns

The Principal that was produced by authentication.

getCurrentAge() Method

public long getCurrentAge()
throws IllegalStateException
Returns the conversation's current age (in seconds).

Returns

The number of seconds that have passed since the conversation started.

Exceptions

IllegalStateException
If the method is called from a service instance that is not conversational.

getCurrentIdleTime() Method

public long getCurrentIdleTime()
throws IllegalStateException
Gets the number of seconds since the last client request, or since the conversation's maximum idle time was reset.

Returns

The number of seconds since the last activity affecting the conversation.

Exceptions

IllegalStateException
if the method is called from a service instance that is not conversational.

getLogger(String) Method

public Logger getLogger(String name)
Gets an instance of the Logger class, which you can use to send messages from your code to a log file.

Use getLogger to log messages from your web service Java code to a text file. By default, for the samples domain installed with WebLogic Workshop web services, this text file is located at the following path of your WebLogic Workshop installation:
 BEA_HOME/weblogic81/samples/workshop/jws.log
 
Use the categoryName parameter to specify category text that will be included with log entries. For example, you might specify the name of the JWS file so that you can more easily find relevant messages when scanning the log file. A log message might appear as follows for an entry in which categoryName is "MyService".
 16:18:11 ERROR MyService: My log message.
 
Note: You can customize aspects of the logging configuration, including the name of the application log file, its size limit, and so on. You configure logging using the workshopLogCfg.xml file. For more information, search the WebLogic Workshop documentation for "workshopLogCfg.xml Configuration File".

The Logger class returned by this method includes four methods that you can use to print log entries to a text file. For more information, see the Logger class.

Parameters

name
The name of the category by which log messages should be grouped.

Returns

A Logger class that may be used to send messages to the application log.

getMaxAge() Method

public long getMaxAge()
throws IllegalStateException
Gets the time representing the longest the conversation may remain active before finishing.

Returns

The number of seconds since the conversation started before which it will finish.

Exceptions

IllegalStateException
if the method is called from a service instance that is not conversational.

getMaxIdleTime() Method

public long getMaxIdleTime()
throws IllegalStateException
Gets the number of seconds that the conversation can remain idle before finishing due to client inactivity. A conversation is idle if the service is not receiving incoming messages through an operation method. Note that messages received through callback handlers do not reset a conversation idle time.

Returns

The number of seconds that the conversation can remain idle before finishing due to client inactivity.

Exceptions

IllegalStateException
if the method is called from a service instance that is not conversational.

getService() Method

public ServiceHandle getService()
Returns a ServiceHandle instance for the currently active service instance. You can use this handle to query service information such as the conversation ID, the protocol scheme initiating the current request, and the URL of the service.

Returns

A weblogic.jws.ServiceHandle object representing the current web service.

isCallerInRole(String) Method

public boolean isCallerInRole(String roleName)
Returns true if the authenticated principal is within the specified security role.

Parameters

roleName
The name of the security role against which to check the authenticated principal.

Returns

true if the principal is within the specified security role; false if they are not.

isFinished() Method

public boolean isFinished()
Returns whether or not this conversation instance has had finish() called on it (indicating that code has requested termination of this conversation instance).

You can finish a conversation by calling the finishConversation method on the conversation instance.

Returns

true if the conversation has finished; false if it hasn't.

resetIdleTime() Method

public void resetIdleTime()
throws IllegalStateException
Resets the timer measuring the number of seconds since the last activity for the current conversation. You can use this method to reset the timer for other service activity beyond client requests.

Returns

The number of seconds before which the conversation will be finished due to client inactivity.

Exceptions

IllegalStateException
if the method is called from a service instance that is not conversational.

setMaxAge(Date) Method

public void setMaxAge(Date date)
throws IllegalStateException, IllegalArgumentException
Sets a new maximum age for the conversation to an absolute Date. If the date parameter is in the past, the conversation will finish immediately.

Calling this method from a web service's code sets the maximum conversation age (relative to the current time) for that service instance. The date parameter marks the time after which WebLogic Server will be allowed to finish this conversation. Note that setting the maximum age with this method overrides the default setting or the setting given in the service's JWS file. This is an absolute age that isn't affected by network traffic.

Parameters

date
The time after which the conversation should finish; null to disable the age timeout.

Exceptions

IllegalStateException
if the method is called from a service instance that is not conversational.
IllegalArgumentException
If this method has passed an illegal or inappropriate argument.

setMaxAge(String) Method

public void setMaxAge(String duration)
throws IllegalStateException, IllegalArgumentException
Sets a conversation's maximum age by specifying a duration as a string.

Call this method to set the maximum conversation age (relative to the current time) for the conversation. The duration parameter marks the time after which the WebLogic Server will be allowed to finish this conversation. Note that setting the maximum age with this method overrides the default setting or the setting given in the service's JWS file. This is an absolute age that isn't affected by network traffic.

If the duration value results in zero seconds, the maximum age timeout will be disabled. If the duration value is in the past, the conversation will finish immediately.

The duration value is considered to be relative to the current time, not to the start of the conversation.

Parameters

duration
The period after which the conversation will finish.

Exceptions

IllegalStateException
if the method is called from a service instance that is not conversational.
IllegalArgumentException
If this method has passed an illegal or inappropriate argument.

setMaxIdleTime(long) Method

public void setMaxIdleTime(long seconds)
throws IllegalStateException, IllegalArgumentException
Sets the number of seconds that the conversation can remain idle before finishing due to client inactivity.

Conversation idle time is the amount of time that can pass between incoming messages before the service instance is finished due to client inactivity. You can initialize a conversation's idle time to a default through the setting given at the top of the JWS file, but each instance can be set to a different idle time value through the setMaxIdleTime or setMaxIdleTime method.

To disable idle time expiration, set the maximum idle time value to zero.

The timer associated with tracking the idle time will automatically reset whenever a request is received from a web service's client or when resetIdleTime method is called.

Parameters

seconds
The number of seconds the conversation can remain idle before it will expire.

Exceptions

IllegalStateException
if the method is called from a service instance that is not conversational.
IllegalArgumentException
If this method has passed an illegal or inappropriate argument.

setMaxIdleTime(String) Method

public void setMaxIdleTime(String duration)
throws IllegalStateException, IllegalArgumentException
Sets the number of seconds (as a String) that the conversation can remain idle before finishing due to client inactivity.

Conversation idle time is the amount of time that can pass between incoming messages before the service instance is finished due to client inactivity. You can initialize a conversation's idle time to a default through the setting given at the top of the JWS file, but each instance can be set to a different idle time value through the setMaxIdleTime or setMaxIdleTime method.

To disable idle time expiration, set the maximum idle time value to zero.

The timer associated with tracking the idle time will automatically reset whenever a request is received from a web service's client or when resetIdleTime method is called.

Parameters

duration
The number of seconds the conversation can remain idle before it will expire.

Exceptions

IllegalStateException
if the method is called from a service instance that is not conversational.
IllegalArgumentException
If this method has passed an illegal or inappropriate argument.