IBM Rational Performance Tester SDK

com.ibm.rational.test.lt.recorder.core.session
Interface IRecordingSession


public interface IRecordingSession

A recording session represents a concrete session involving one or more recorders and zero or more clients. Clients initiate traffic which is captured by recorders they are bound to. A session can be started and stopped. A session and its recording components is parameterized by its configuration. A session persists the data captured by the recorders in its persistence file. It has a state and can observed by listeners.

See Also:
RecorderCore.createRecordingSession(RecordingSessionConfiguration)

Method Summary
 void addListener(IRecordingSessionListener listener)
           
 boolean areDependenciesSatisfied()
          Returns whether all the required extensions necessary to read the recording session content are available.
 long currentTime()
          Returns a value that corresponds to the current time.
 int getAnnotationCount()
          Returns the count of annotations that were emitted during the session.
 List<IRecorderPacketReference> getAnnotationPacketReferences(IPacketReferenceInputStream stream)
          Returns the annotations packet references that were emitted during the session.
 List<IRecorderAnnotationPacket> getAnnotationPackets()
          Returns the annotations packets that were emitted during the session.
 IClient getClient(short clientId)
           
 List<IClient> getClients()
           
 RecordingSessionConfiguration getConfiguration()
           
 IPacketInputStream getContent()
          Returns the recorded content of the session, as a packet input stream.
 IPacketReferenceInputStream getContentAsReference()
          Returns the recorded content of the session, as a packet reference input stream.
 com.ibm.rational.test.lt.recorder.core.encrypt.EncryptionLevel getEncryptionLevel()
          Returns the encryption level used to protect access to this recording session.
 IFile getPersistenceFile()
           
 IRecorder getRecorder(short recorderId)
           
 List<IRecorder> getRecorders()
           
 RecordingSessionState getState()
          Returns the current state of the session.
 IRecordingSessionStatistics getStatistics()
          Returns statistics about the data stored in the persistence file.
 ITimeReference getTimeReference()
          Returns the time reference that allows to convert back and forth time expressed in the recording session clock and times expressed in milliseconds.
 boolean isFromFutureVersion()
          Returns true if this recording session is from a future version.
 boolean isUpgradeNeeded()
          Returns whether the recording session needs to be upgraded to achieve full performance.
 void killClients()
           
 void removeListener(IRecordingSessionListener listener)
           
 void sendMessage(Message message)
          Sends a message to some components of the recording session.
 void setEncryptionLevel(com.ibm.rational.test.lt.recorder.core.encrypt.IEncryptionParameter encryptionParameter)
          Modifies the encryption level of the file.
 void start()
           
 void stop()
           
 void unlock(com.ibm.rational.test.lt.recorder.core.encrypt.IEncryptionParameter encryptionParameter)
          Unlocks access to this recording session by providing the encryption parameter.
 void upgrade()
          Performs upgrade of the recording session file.
 

Method Detail

getRecorders

List<IRecorder> getRecorders()

getClients

List<IClient> getClients()

getRecorder

IRecorder getRecorder(short recorderId)

getClient

IClient getClient(short clientId)

start

void start()

stop

void stop()

killClients

void killClients()

getPersistenceFile

IFile getPersistenceFile()

getConfiguration

RecordingSessionConfiguration getConfiguration()

addListener

void addListener(IRecordingSessionListener listener)

removeListener

void removeListener(IRecordingSessionListener listener)

getState

RecordingSessionState getState()
Returns the current state of the session. Note that when state is tested for a decision based on its value, the call to this method, the test, and the decision should be grouped together in a synchronized block on this component.
For instance:
 synchronized(session) {
   if (session.getState() == RecordingSessionState.RUNNING) {
     session.stop(); // This method may throw an IllegalStateException
                     // if invoked while the session is in STOPPING_CLIENTS state
   }
 }
 

Returns:
the current state of the session

sendMessage

void sendMessage(Message message)
Sends a message to some components of the recording session. The destination is specified within the message itself.

Parameters:
message -

currentTime

long currentTime()
Returns a value that corresponds to the current time. All recorders and clients share the same clock, and the values obtained using this method can be compared to establish an ordering between events.
This method can be called only while the session is active (i.e. it started but not terminated).

Returns:
the current time.

getStatistics

IRecordingSessionStatistics getStatistics()
Returns statistics about the data stored in the persistence file.

Returns:
statistics about the data stored in the persistence file. This value is null before the session is started, and it may be null if the session does not persist recorded data (because no persistence file has been specified in the recording session configuration).

getTimeReference

ITimeReference getTimeReference()
Returns the time reference that allows to convert back and forth time expressed in the recording session clock and times expressed in milliseconds. The time reference is null if the session has not started yet (i.e. when IRecordingSession.getState() returns RecordingSessionState.INITIAL).

Returns:
the time reference.

getContent

IPacketInputStream getContent()
                              throws IOException
Returns the recorded content of the session, as a packet input stream. If the session is not terminated, the returned stream is blocking, i.e. its method readPacket() may block until the next packet is available, or until the session terminated.

Returns:
The content as a packet input stream. The returned stream must be closed by the caller. null if the no output file was specified in the recording session configuration.
Throws:
IOException - Any exception thrown by the underlying I/O layer.

getContentAsReference

IPacketReferenceInputStream getContentAsReference()
                                                  throws IOException
Returns the recorded content of the session, as a packet reference input stream. If the session is not terminated, the returned stream is blocking, i.e. its read methods may block until the next packet is available, or until the session terminated.

Returns:
The content as a packet reference input stream. The returned stream must be closed by the caller. null if the no output file was specified in the recording session configuration.
Throws:
IOException - Any exception thrown by the underlying I/O layer.

getAnnotationPackets

List<IRecorderAnnotationPacket> getAnnotationPackets()
                                                     throws IOException
Returns the annotations packets that were emitted during the session. The returned value is equivalent to the result of iterating through the whole content and selecting only packets of type IRecorderAnnotationPacket, but it is generally much more efficient.

Returns:
the annotations packets that were emitted during the session
Throws:
IOException

getAnnotationPacketReferences

List<IRecorderPacketReference> getAnnotationPacketReferences(IPacketReferenceInputStream stream)
                                                             throws IOException
Returns the annotations packet references that were emitted during the session. The returned value is equivalent to the result of iterating through the whole content and selecting only references to packets of type IRecorderAnnotationPacket, but it is generally much more efficient.

Parameters:
stream - A content stream holding the returned references. This stream must have been obtained through a call to IRecordingSession.getContentAsReference() on this recording session.
Returns:
the references to annotations packets that were emitted during the session
Throws:
IOException

getAnnotationCount

int getAnnotationCount()
Returns the count of annotations that were emitted during the session. The return value is equal to IRecordingSession.getAnnotationPackets().size(), but much more efficient.

Returns:
the count of annotations that were emitted during the session

isUpgradeNeeded

boolean isUpgradeNeeded()
Returns whether the recording session needs to be upgraded to achieve full performance. A recording session needs to be upgraded if it was produced by a previous version of the framework, or contains packets produced with a previous version of an extension, and if persistence changes have occurred since this version.

Returns:
true if the recording session needs upgrading, false if its format is up-to-date.

upgrade

void upgrade()
Performs upgrade of the recording session file. This method launches a background job that performs upgrade. While the recording session is upgraded, its state is RecordingSessionState.CONVERTING. Invokers can be notified of the upgrade completion by registering a state listener and checking when the state changes from RecordingSessionState.CONVERTING to RecordingSessionState.TERMINATED. This method does nothing if the recording session is already up-to-date. This method throws an exception if all extensions necessary to load the packets are not installed (as reported by IRecordingSession.areDependenciesSatisfied()).


areDependenciesSatisfied

boolean areDependenciesSatisfied()
Returns whether all the required extensions necessary to read the recording session content are available. If all dependencies are satisfied, the recording session can be read, otherwise IRecordingSession.getContent() and IRecordingSession.getContentAsReference() will throw an exception.

Returns:

getEncryptionLevel

com.ibm.rational.test.lt.recorder.core.encrypt.EncryptionLevel getEncryptionLevel()
Returns the encryption level used to protect access to this recording session.

Returns:
the encryption level used to protect access to this recording session.

setEncryptionLevel

void setEncryptionLevel(com.ibm.rational.test.lt.recorder.core.encrypt.IEncryptionParameter encryptionParameter)
Modifies the encryption level of the file. This is a long-running operation resulting in the complete rewriting of the persistence files. While the recording session is converted, its state is RecordingSessionState.CONVERTING. Invokers can be notified of the operation completion by registering a state listener and checking when the state changes from RecordingSessionState.CONVERTING to RecordingSessionState.TERMINATED. This method does nothing if the recording session already has the same encryption method. This method throws an exception if all extensions necessary to load the packets are not installed (as reported by IRecordingSession.areDependenciesSatisfied()).

Parameters:
encryptionParameter - The new encryption parameter.

unlock

void unlock(com.ibm.rational.test.lt.recorder.core.encrypt.IEncryptionParameter encryptionParameter)
Unlocks access to this recording session by providing the encryption parameter. The session remains unlocked while it is in memory. This operation does nothing if the session has already been unlocked.

Parameters:
encryptionParameter - The encryption parameter.

isFromFutureVersion

boolean isFromFutureVersion()
Returns true if this recording session is from a future version.


IBM Rational Performance Tester SDK

© Copyright IBM Corp. 2012. All rights reserved.