com.ibm.dse.services.cics
Class CICSConnection

java.lang.Object
  |
  +--com.ibm.dse.base.DSENotifier
        |
        +--com.ibm.dse.base.Service
              |
              +--com.ibm.dse.services.cics.CICSConnection

public class CICSConnection
extends Service
implements CICSConnectionService, com.ibm.ctg.client.Callbackable, Handler

This class maps a CICS connection using an ECI requests.

See Also:
Serialized Form

Field Summary
protected  DataReceivedListener aDataReceivedListener
           
protected  ErrorReceivedListener aErrorReceivedListener
           
protected  SessionClosedListener aSessionClosedListener
           
protected  SessionEstablishedListener aSessionEstablishedListener
           
static java.lang.String COMPID
           
protected  java.lang.Thread restablishConn
           
protected static java.lang.String SPACE
           
protected static java.lang.String STR
           
 
Fields inherited from class com.ibm.dse.base.Service
externalizer
 
Fields inherited from class com.ibm.dse.base.DSENotifier
handlersList, name
 
Fields inherited from interface com.ibm.dse.services.comms.CommonCommunicationsService
CLOSED, DATA, DATASENT, ERROR, OPENED, RECEIVERC, TIMEOUT
 
Constructor Summary
CICSConnection()
          This constructor creates a CICSConnection object.
CICSConnection(java.lang.String aName)
          This constructor creates a CICSConnection object named aName.
 
Method Summary
 void addDataReceivedListener(DataReceivedListener newListener)
          Adds a new DataReceivedListener.
 void addErrorReceivedListener(ErrorReceivedListener newListener)
          Adds a new ErrorReceivedListener.
 void addSessionClosedListener(SessionClosedListener newListener)
          Adds a new SessionClosedListener.
 void addSessionEstablishedListener(SessionEstablishedListener newListener)
          Adds a new SessionEstablishedListener.
 void ccClose()
          Closes the CICS connection.
 void ccOpen()
          Opens a CICS connection.
 CCMessage ccReceiveData(long aTimeout)
          Reads the data that has been received.
 void ccSendData(java.lang.String aString)
          Sends aString through the communications channel.
 CCMessage ccSendReceive(java.lang.String aString, long aTimeout)
          Sends a string and waits until the data is received or the timeout is reached.
 void closeConnection()
          Closes the CICS connection.
 Handler dispatchEvent(DSEEventObject anEvent)
          Generates the event anEvent.
 void establishConnection()
          Establishes a CICS connection.
protected  void fireHandleEvent(DataReceivedEvent event)
          Fires a signal when a data is received.
protected  void fireHandleEvent(ErrorReceivedEvent event)
          Fires a signal when an error is received.
protected  void fireHandleEvent(SessionClosedEvent event)
          Fires a signal when the session is closed.
protected  void fireHandleEvent(SessionEstablishedEvent event)
          Fires a signal when the session is established.
 boolean getAutomaticConnectionEstablishment()
          Returns the value of the automaticConnectionestablishment attribute.
 java.lang.String getCcClosedEventName()
          Returns the name of the closed event
 java.lang.String getCcDataReceivedEventName()
          Returns the name of the data received event
 java.lang.String getCcErrorReceivedEventName()
          Returns the name of the error received event
 java.lang.String getCcOpenedEventName()
          Returns the name of the opened event
 java.lang.String getCodePage()
          Returns the value of the cdPage attribute.
 java.lang.String getData()
          Returns the response.
 int getEstablishSessionCounter()
          Returns the value of the establishSessionCounter attribute.
 int getEstablishSessionRetries()
          Returns the value of the establishSessionRetries attribute.
 java.lang.String getGatewayName()
          Returns the value of the gatewayName attribute.
 int getGatewayPort()
          Returns the value of the getewayPort attribute.
 java.lang.String getProgramName()
          Returns the value of the programName attribute.
 int getRc()
          Returns the value of the rc attribute.
 java.lang.String getServerName()
          Returns the value of the serverName attribute.
 java.lang.String getStatus()
          Returns the value of the status attribute.
 boolean getSynchronousMode()
          Returns the value of the synchronousTx attribute
 int getTimeBetweenRetries()
          Returns the value of the timeBetweenRetries attribute.
 java.lang.String getTransactionId()
          Returns the value of the transactionId attribute.
 java.lang.String getUserId()
          Returns the value of the userId attribute.
 void handleEvent(java.lang.String anEventName, java.lang.String aNotifierName, Context aContext)
          Calls the EventManager class that registers the handler to the local notifier if it is defined or adds it to its own list of handlers if the notifier is remote.
 void handleEvent(java.lang.String anEventName, java.lang.String aNotifierName, Context aContext, java.lang.String aTID)
          Calls the EventManager class that registers the handler to the local notifier if it is defined or adds it to its own list of handlers if the notifier is remote.
 void initCommArea(int size)
          Initializes the communications area and sets its size.
 java.lang.Object initializeFrom(Tag aTag)
          Initializes a CICSConnection object with the aTag attributes.
protected  void initInstance()
          Tries to establish a session with the CICS partner.
 boolean isFree()
          Returns true if this CICS connection is ready to be used.
 boolean isOffline()
          Returns true if the host session is down.
 void removeDataReceivedListener(DataReceivedListener aListener)
          Removes the aListener.
 void removeErrorReceivedListener(ErrorReceivedListener aListener)
          Removes the aListener.
 void removeSessionClosedListener(SessionClosedListener aListener)
          Removes the aListener.
 void removeSessionEstablishedListener(SessionEstablishedListener aListener)
          Removes the aListener.
 void resetCommArea()
          Clears the communications area..
protected  void restablishConnection()
          Tries to establish the session.
 void run()
          Run method.
 void setAutomaticConnectionEstablishment(boolean automatic)
          Sets the value of the automaticConnection property.
 void setCodePage(java.lang.String cP)
          Sets the value of the cdPage property.
 void setEstablishSessionCounter(int value)
          Sets the value of the establishSessionCounter property.
 void setEstablishSessionRetries(int retries)
          Sets the value of the establishSessionRetried property.
 void setGatewayName(java.lang.String aName)
          Sets the value of the gatewayName property.
 void setGatewayPort(int aPort)
          Sets the value of the gatewayPort property.
 void setInUse(boolean inUse)
          Sets the value of the used property.
 void setPassword(java.lang.String aPassword)
          Sets the value of the password property.
 void setProgramName(java.lang.String aProgram)
          Sets the value of the programName property.
 void setResults(com.ibm.ctg.client.GatewayRequest req)
          Is invoked when the answer of an asynchronous ECIRequest has been received.
 void setServerName(java.lang.String aName)
          Sets the value of the serverName property.
 void setSynchronousMode(boolean b)
          Sets the value of the synchronousTx property.
 void setTimeBetweenRetries(int time)
          Sets the value of the timeBetweenRetries property.
 void setTransactionId(java.lang.String aId)
          Sets the value of the transactionId property.
 void setUserId(java.lang.String aUser)
          Sets the value of the userId property.
 void stopHandlingEvent(java.lang.String anEventName, java.lang.String aNotifierName, Context aContext)
          Allows the Handler to stop receiving a specific event for which it was registered previously.
 void stopHandlingEvent(java.lang.String anEventName, java.lang.String aNotifierName, Context aContext, java.lang.String aTID)
          Allows the Handler to stop receiving a specific event for which it was registered previously.
 void terminate()
          Closes the connection and frees all the resources used by the service.
 java.lang.String toString()
          Returns a visual representation of this object.
 
Methods inherited from class com.ibm.dse.base.Service
externalizer, getExternalizer, getTagName, readExternal, readExternal, readObject, removeExternal, setExternalizer, toStrings, toTags, writeExternal, writeExternal
 
Methods inherited from class com.ibm.dse.base.DSENotifier
addHandler, getHandlersList, getName, removeHandler, setName, signalEvent, signalEvent, signalEvent
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

aDataReceivedListener

protected transient DataReceivedListener aDataReceivedListener

aErrorReceivedListener

protected transient ErrorReceivedListener aErrorReceivedListener

aSessionClosedListener

protected transient SessionClosedListener aSessionClosedListener

aSessionEstablishedListener

protected transient SessionEstablishedListener aSessionEstablishedListener

restablishConn

protected java.lang.Thread restablishConn

STR

protected static java.lang.String STR

SPACE

protected static java.lang.String SPACE

COMPID

public static final java.lang.String COMPID
Constructor Detail

CICSConnection

public CICSConnection()
This constructor creates a CICSConnection object.

CICSConnection

public CICSConnection(java.lang.String aName)
               throws java.io.IOException
This constructor creates a CICSConnection object named aName.
Parameters:
aName - java.lang.String
Throws:
java.io.IOException. -  
Method Detail

addDataReceivedListener

public void addDataReceivedListener(DataReceivedListener newListener)
Adds a new DataReceivedListener.
Parameters:
newListener - com.ibm.dse.services.cics.DataReceivedListener

addErrorReceivedListener

public void addErrorReceivedListener(ErrorReceivedListener newListener)
Adds a new ErrorReceivedListener.
Parameters:
newListener - com.ibm.dse.services.cics.ErrorReceivedListener

addSessionClosedListener

public void addSessionClosedListener(SessionClosedListener newListener)
Adds a new SessionClosedListener.
Parameters:
newListener - com.ibm.dse.services.cics.DataReceivedListener

addSessionEstablishedListener

public void addSessionEstablishedListener(SessionEstablishedListener newListener)
Adds a new SessionEstablishedListener.
Parameters:
newListener - com.ibm.dse.services.cics.DataReceivedListener

ccClose

public void ccClose()
             throws DSECCException
Closes the CICS connection.
Throws:
com.ibm.dse.services.comms.DSECCException. -  

ccOpen

public void ccOpen()
            throws DSECCException
Opens a CICS connection.
Throws:
com.ibm.dse.services.comms.DSECCException. -  

ccReceiveData

public CCMessage ccReceiveData(long aTimeout)
                        throws DSECCException
Reads the data that has been received.
Parameters:
aTimeout - long
Returns:
com.ibm.dse.services.comms.CCMessage
Throws:
com.ibm.dse.services.comms.DSECCException. -  

ccSendData

public void ccSendData(java.lang.String aString)
                throws DSECCException
Sends aString through the communications channel. It returns control immediately. When the response is received, two events can be signaled, DataReceived event in case of data received or ErrorReceived, in case of error.
Parameters:
aString - java.lang.String
Throws:
com.ibm.dse.services.comms.DSECCException. -  

ccSendReceive

public CCMessage ccSendReceive(java.lang.String aString,
                               long aTimeout)
                        throws DSECCException
Sends a string and waits until the data is received or the timeout is reached.
Parameters:
aString - java.lang.String
aTimeout - long
Returns:
com.ibm.dse.services.comms.CCMessage
Throws:
com.ibm.dse.services.comms.DSECCException. -  

closeConnection

public void closeConnection()
                     throws java.io.IOException
Closes the CICS connection.
Specified by:
closeConnection in interface CICSConnectionService
Throws:
java.io.IOException. -  

dispatchEvent

public Handler dispatchEvent(DSEEventObject anEvent)
Generates the event anEvent.

anEvent contains relevant data to be used by the event handler held in a Hashtable, the source of the event and the event name. Any handler is responsible for implementing this method, to check if it is interested in the event and/or pass it to the next interested handler in the chain that is waiting for it.

If the method returns this, the notifier passes the event to the following handler in the chain waiting for it. If the method returns null, the event is not propagated.

The default event processing is to pass the event to the following handler.

Specified by:
dispatchEvent in interface Handler
Parameters:
anEvent - DSEEventObject
Returns:
Handler

establishConnection

public void establishConnection()
Establishes a CICS connection.
Specified by:
establishConnection in interface CICSConnectionService
Tags copied from interface: CICSConnectionService
Throws:
Exception. -  

fireHandleEvent

protected void fireHandleEvent(DataReceivedEvent event)
Fires a signal when a data is received.
Parameters:
event - com.ibm.dse.services.cics.DataReceivedEvent

fireHandleEvent

protected void fireHandleEvent(ErrorReceivedEvent event)
Fires a signal when an error is received.
Parameters:
event - com.ibm.dse.services.cics.ErrorReceivedEvent

fireHandleEvent

protected void fireHandleEvent(SessionClosedEvent event)
Fires a signal when the session is closed.
Parameters:
event - com.ibm.dse.services.cics.SessionClosedEvent

fireHandleEvent

protected void fireHandleEvent(SessionEstablishedEvent event)
Fires a signal when the session is established.
Parameters:
event - com.ibm.dse.services.cics.SessionEstablishedEvent

getAutomaticConnectionEstablishment

public boolean getAutomaticConnectionEstablishment()
Returns the value of the automaticConnectionestablishment attribute.
Returns:
boolean - The current value of automaticConnectionestablishmet.

getCcClosedEventName

public java.lang.String getCcClosedEventName()
Returns the name of the closed event
Returns:
String - The name of the closed event.

getCcDataReceivedEventName

public java.lang.String getCcDataReceivedEventName()
Returns the name of the data received event
Returns:
String - The name of the data received event.

getCcErrorReceivedEventName

public java.lang.String getCcErrorReceivedEventName()
Returns the name of the error received event
Returns:
String - The name of the error received event.

getCcOpenedEventName

public java.lang.String getCcOpenedEventName()
Returns the name of the opened event
Returns:
String - The name of the opened event.

getCodePage

public java.lang.String getCodePage()
Returns the value of the cdPage attribute.
Returns:
String - The current value of cpPage.

getData

public java.lang.String getData()
Returns the response.
Returns:
String

getEstablishSessionCounter

public int getEstablishSessionCounter()
Returns the value of the establishSessionCounter attribute.
Returns:
int - The current value of establishSessionCounter.

getEstablishSessionRetries

public int getEstablishSessionRetries()
Returns the value of the establishSessionRetries attribute.
Returns:
int - The current value of establishSessionRetries.

getGatewayName

public java.lang.String getGatewayName()
Returns the value of the gatewayName attribute.
Specified by:
getGatewayName in interface CICSConnectionService
Returns:
String - The current value of gatewayName.

getGatewayPort

public int getGatewayPort()
Returns the value of the getewayPort attribute.
Specified by:
getGatewayPort in interface CICSConnectionService
Returns:
int - The current value of gatewayPort.

getProgramName

public java.lang.String getProgramName()
Returns the value of the programName attribute.
Specified by:
getProgramName in interface CICSConnectionService
Returns:
String - The current value of programName.

getRc

public int getRc()
Returns the value of the rc attribute.
Returns:
int - The current value of rc.

getServerName

public java.lang.String getServerName()
Returns the value of the serverName attribute.
Specified by:
getServerName in interface CICSConnectionService
Returns:
String - The current value of serverName.

getStatus

public java.lang.String getStatus()
Returns the value of the status attribute.
Specified by:
getStatus in interface CICSConnectionService
Returns:
String - The current value of status.

getSynchronousMode

public boolean getSynchronousMode()
Returns the value of the synchronousTx attribute
Returns:
boolean - The current value of synchronousTx.

getTimeBetweenRetries

public int getTimeBetweenRetries()
Returns the value of the timeBetweenRetries attribute.
Returns:
int - The current value of timeBetweenRetries.

getTransactionId

public java.lang.String getTransactionId()
Returns the value of the transactionId attribute.
Specified by:
getTransactionId in interface CICSConnectionService
Returns:
String - The current value of transactionId.

getUserId

public java.lang.String getUserId()
Returns the value of the userId attribute.
Specified by:
getUserId in interface CICSConnectionService
Returns:
String - The current value of userId.

handleEvent

public void handleEvent(java.lang.String anEventName,
                        java.lang.String aNotifierName,
                        Context aContext)
                 throws DSEInvalidArgumentException
Calls the EventManager class that registers the handler to the local notifier if it is defined or adds it to its own list of handlers if the notifier is remote.
Specified by:
handleEvent in interface Handler
Parameters:
anEventName - String The event name.
aNotifierName - String The notifier name.
aContext - Context The context instance.
Throws:
DSEInvalidArgumentException. -  
DSEHandlerNotFoundException. -  

handleEvent

public void handleEvent(java.lang.String anEventName,
                        java.lang.String aNotifierName,
                        Context aContext,
                        java.lang.String aTID)
                 throws DSEInvalidArgumentException
Calls the EventManager class that registers the handler to the local notifier if it is defined or adds it to its own list of handlers if the notifier is remote.
Specified by:
handleEvent in interface Handler
Parameters:
anEventName - String The event name.
aNotifierName - String The notifier name.
aContext - Context The context instance.
aTID - String The terminal identification.
Throws:
DSEInvalidArgumentException. -  
DSEHandlerNotFoundException. -  

initCommArea

public void initCommArea(int size)
Initializes the communications area and sets its size.
Parameters:
size - int

initializeFrom

public java.lang.Object initializeFrom(Tag aTag)
                                throws java.io.IOException,
                                       DSEException
Initializes a CICSConnection object with the aTag attributes.
Overrides:
initializeFrom in class Service
Parameters:
aTag - com.ibm.dse.base.Tag Contains the name and attributes of the object to be created.
Returns:
Object - An instance of CICSConnection.
Throws:
java.io.IOException - The object can not be created.

initInstance

protected void initInstance()
                     throws DSEInvalidArgumentException,
                            DSECCException
Tries to establish a session with the CICS partner.

isFree

public boolean isFree()
Returns true if this CICS connection is ready to be used.
Returns:
boolean

isOffline

public boolean isOffline()
Returns true if the host session is down.
Returns:
boolean.

removeDataReceivedListener

public void removeDataReceivedListener(DataReceivedListener aListener)
Removes the aListener.
Parameters:
aListener - com.ibm.dse.services.cics.DataReceivedListener

removeErrorReceivedListener

public void removeErrorReceivedListener(ErrorReceivedListener aListener)
Removes the aListener.
Parameters:
aListener - com.ibm.dse.services.cics.DataReceivedListener

removeSessionClosedListener

public void removeSessionClosedListener(SessionClosedListener aListener)
Removes the aListener.
Parameters:
aListener - com.ibm.dse.services.cics.SessionClosedListener

removeSessionEstablishedListener

public void removeSessionEstablishedListener(SessionEstablishedListener aListener)
Removes the aListener.
Parameters:
aListener - com.ibm.dse.services.cics.SessionEstablishedListener

resetCommArea

public void resetCommArea()
Clears the communications area..

restablishConnection

protected void restablishConnection()
Tries to establish the session.

run

public void run()
Run method. It is invoked when the reply of an asynchronous ECIRequest has been received. Before calling this method, the setResults method is called.

setAutomaticConnectionEstablishment

public void setAutomaticConnectionEstablishment(boolean automatic)
Sets the value of the automaticConnection property.
Parameters:
automatic - boolean The new value of the property.

setCodePage

public void setCodePage(java.lang.String cP)
Sets the value of the cdPage property.
Parameters:
cP - String The new value of the property.

setEstablishSessionCounter

public void setEstablishSessionCounter(int value)
Sets the value of the establishSessionCounter property.
Parameters:
value - int The new value of the property.

setEstablishSessionRetries

public void setEstablishSessionRetries(int retries)
Sets the value of the establishSessionRetried property.
Parameters:
retries - int The new value of the property.

setGatewayName

public void setGatewayName(java.lang.String aName)
Sets the value of the gatewayName property.
Specified by:
setGatewayName in interface CICSConnectionService
Parameters:
aName - String The new value of the property.

setGatewayPort

public void setGatewayPort(int aPort)
Sets the value of the gatewayPort property.
Specified by:
setGatewayPort in interface CICSConnectionService
Parameters:
aPort - int The new value of the property.

setInUse

public void setInUse(boolean inUse)
Sets the value of the used property.
Parameters:
inUsed - boolean The new value of the property.

setPassword

public void setPassword(java.lang.String aPassword)
Sets the value of the password property.
Specified by:
setPassword in interface CICSConnectionService
Parameters:
aPassword - String The new value of the property.

setProgramName

public void setProgramName(java.lang.String aProgram)
Sets the value of the programName property.
Specified by:
setProgramName in interface CICSConnectionService
Parameters:
aProgram - String The new value of the property.

setResults

public void setResults(com.ibm.ctg.client.GatewayRequest req)
Is invoked when the answer of an asynchronous ECIRequest has been received.
Specified by:
setResults in interface com.ibm.ctg.client.Callbackable
Parameters:
req - com.ibm.ctg.client.GatewayRequest

setServerName

public void setServerName(java.lang.String aName)
Sets the value of the serverName property.
Specified by:
setServerName in interface CICSConnectionService
Parameters:
aName - String The new value of the property.

setSynchronousMode

public void setSynchronousMode(boolean b)
Sets the value of the synchronousTx property.
Parameters:
synchronousMode - boolean The new value of the property.

setTimeBetweenRetries

public void setTimeBetweenRetries(int time)
Sets the value of the timeBetweenRetries property.
Parameters:
time - int The new value of the property.

setTransactionId

public void setTransactionId(java.lang.String aId)
Sets the value of the transactionId property.
Specified by:
setTransactionId in interface CICSConnectionService
Parameters:
aTxId - String The new value of the property.

setUserId

public void setUserId(java.lang.String aUser)
Sets the value of the userId property.
Specified by:
setUserId in interface CICSConnectionService
Parameters:
aUser - String The new value of the property.

stopHandlingEvent

public void stopHandlingEvent(java.lang.String anEventName,
                              java.lang.String aNotifierName,
                              Context aContext)
                       throws DSEInvalidArgumentException,
                              DSEHandlerNotFoundException
Allows the Handler to stop receiving a specific event for which it was registered previously.
Specified by:
stopHandlingEvent in interface Handler
Parameters:
anEventName - String The event name.
aNotifierName - String The notifier name.
aContext - Context The context instance.
Throws:
DSEInvalidArgumentException. -  
DSEHandlerNotFoundException. -  

stopHandlingEvent

public void stopHandlingEvent(java.lang.String anEventName,
                              java.lang.String aNotifierName,
                              Context aContext,
                              java.lang.String aTID)
                       throws DSEInvalidArgumentException,
                              DSEHandlerNotFoundException
Allows the Handler to stop receiving a specific event for which it was registered previously.
Specified by:
stopHandlingEvent in interface Handler
Parameters:
anEventName - String The event name.
aNotifierName - String The notifier name.
aContext - Context The context instance.
aTID - String The terminal identification.
Throws:
DSEInvalidArgumentException. -  
DSEHandlerNotFoundException. -  

terminate

public void terminate()
Closes the connection and frees all the resources used by the service.
Specified by:
terminate in interface CICSConnectionService
Overrides:
terminate in class Service

toString

public java.lang.String toString()
Returns a visual representation of this object.
Overrides:
toString in class Service
Returns:
java.lang.String - The object visual representation.