org.jlab.coda.et
Class SystemUse

java.lang.Object
  org.jlab.coda.et.SystemUse

public class SystemUse

extends java.lang.Object

This class implements an object which allows a user to interact with an ET system. It is not the ET system itself, but rather a proxy which communicates over the network with the real ET system.

Field Summary

(package private) java.io.DataInputStream	in Data input stream built on top of the socket's input stream (with an intervening buffered input stream).
(package private) java.io.DataOutputStream	out Data output stream built on top of the socket's output stream (with an intervening buffered output stream).

Constructor Summary

SystemUse(SystemOpenConfig _config)
Create a new SystemUse object.

SystemUse(SystemOpenConfig _config, int _debug)
Create a new SystemUse object.

SystemUse(SystemOpen _sys, int _debug)
Create a new SystemUse object.

Method Summary

boolean	alive() Is the ET system alive - still up and running?
Attachment	attach(Station station) Create an attachment to a station.
void	close() Close the ET system.
Station	createStation(StationConfig config, java.lang.String name) Creates a new station placed at the end of the linked list of stations.
Station	createStation(StationConfig config, java.lang.String name, int position) Creates a new station at a specified position in the linked list of stations.
Station	createStation(StationConfig config, java.lang.String name, int position, int parallelPosition) Creates a new station at a specified position in the linked list of stations and in a specified position in a linked list of parallel stations if it is a parallel station.
void	detach(Attachment att) Remove an attachment from a station.
void	dumpEvents(Attachment att, Event[] evs) Dispose of unwanted events in an ET system.
void	dumpEventsList(Attachment att, java.util.List eventList) Dispose of unwanted events in an ET system.
int	getAttachmentsMax() Gets the maximum number of attachments allowed in the ET system.
SystemOpenConfig	getConfig() Gets a copy of the configuration used to specify how to open the ET system.
AllData	getData() Gets all information about the ET system.
int	getDebug() Gets the debug output level.
Event[]	getEvents(Attachment att, int mode, int microSec, int count) Get events from an ET system.
Event[]	getEvents2(Attachment att, int mode, int microSec, int count) Get events from an ET system.
int	getEventSize() Gets the "normal" event size in bytes.
java.util.ArrayList	getEventsList(Attachment att, int mode, int microSec, int count) Get events from an ET system.
int	getHeartbeat() Gets the ET system heartbeat.
int[]	getHistogram() Gets histogram containing data showing how many events in GRAND_CENTRAL's input list when new events are requested by users.
java.lang.String	getHost() Gets the ET system's host name.
int	getLanguage() Gets the ET system's implementation language.
int	getNumAttachments() Gets the number of attachments in the ET system.
int	getNumEvents() Gets the number of events in the ET system.
int	getNumProcesses() Gets the number of local processes in the ET system.
int	getNumStations() Gets the number of stations in the ET system.
int	getNumTemps() Gets the number of temp events in the ET system.
int	getPid() Gets the UNIX pid of the ET system process.
int	getProcessesMax() Gets the maximum number of local processes allowed in the ET system.
int	getStationParallelPosition(Station station) Gets the position of a parallel station in its linked list of parallel stations.
int	getStationPosition(Station station) Gets the position of a station in the linked list of stations.
int	getStationsMax() Gets the maximum number of stations allowed in the ET system.
int	getTcpPort() Gets the tcp server port number.
int	getTempsMax() Gets the maximum number of temp events allowed in the ET system.
Event[]	newEvents(Attachment att, int mode, int microSec, int count, int size) Get new or unused events from an ET system.
java.util.ArrayList	newEventsList(Attachment att, int mode, int microSec, int count, int size) Get new or unused events from an ET system.
void	putEvents(Attachment att, Event[] evs) Put events into an ET system.
void	putEvents2(Attachment att, Event[] evs) Put events into an ET system.
void	putEventsList(Attachment att, java.util.List eventList) Put events into an ET system.
void	removeStation(Station station) Removes an existing station.
void	setDebug(int val) Sets the debug output level.
void	setStationPosition(Station station, int position, int parallelPosition) Changes the position of a station in the linked list of stations.
boolean	stationAttached(Station station, Attachment att) Tells if an attachment is attached to a station.
boolean	stationExists(java.lang.String name) Tells if a station exists.
Station	stationNameToObject(java.lang.String name) Gets a station's object representation from its name.
void	wakeUpAll(Station station) Wake up all attachments waiting to read events from a station's empty input list.
void	wakeUpAttachment(Attachment att) Wake up an attachment that is waiting to read events from a station's empty input list.

Methods inherited from class java.lang.Object

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

Field Detail

in

java.io.DataInputStream in

Data input stream built on top of the socket's input stream (with an intervening buffered input stream).

out

java.io.DataOutputStream out

Data output stream built on top of the socket's output stream (with an intervening buffered output stream).

Constructor Detail

SystemUse

public SystemUse(SystemOpenConfig _config,
                 int _debug)
          throws java.io.IOException,
                 java.net.UnknownHostException,
                 EtException,
                 EtTooManyException

Create a new SystemUse object.

Parameters:

_config - SystemOpenConfig object to specify how to open the ET system of interest

_debug - debug level (e.g. Constants.debugInfo)

Throws:

java.io.IOException - if problems with network comunications

java.net.UnknownHostException - if the host address(es) is(are) unknown

EtException - if the responding ET system has the wrong name, runs a different version of ET, or has a different value for Constants.stationSelectInts

EtTooManyException - if there were more than one valid response when policy is set to Constants.policyError and we are looking either remotely or anywhere for the ET system.

SystemUse

public SystemUse(SystemOpenConfig _config)
          throws java.io.IOException,
                 java.net.UnknownHostException,
                 EtException,
                 EtTooManyException

Create a new SystemUse object. Debug level set to print only errors.

Parameters:

_config - SystemOpenConfig object to specify how to open the ET system of interest

Throws:

java.io.IOException - if problems with network comunications

java.net.UnknownHostException - if the host address(es) is(are) unknown

EtException - if the responding ET system has the wrong name, runs a different version of ET, or has a different value for Constants.stationSelectInts

EtTooManyException - if there were more than one valid response when policy is set to Constants.policyError and we are looking either remotely or anywhere for the ET system.

SystemUse

public SystemUse(SystemOpen _sys,
                 int _debug)
          throws java.io.IOException,
                 java.net.UnknownHostException,
                 EtException,
                 EtTooManyException

Create a new SystemUse object.

Parameters:

_sys - SystemOpen object to specify a connection to the ET system of interest

_debug - debug level (e.g. Constants.debugInfo)

Throws:

java.io.IOException - if problems with network comunications

java.net.UnknownHostException - if the host address(es) is(are) unknown

EtException - if the responding ET system has the wrong name, runs a different version of ET, or has a different value for Constants.stationSelectInts

EtTooManyException - if there were more than one valid response when policy is set to Constants.policyError and we are looking either remotely or anywhere for the ET system.

Method Detail

close

public void close()

Close the ET system.

alive

public boolean alive()

Is the ET system alive - still up and running?

Returns:

true if the ET system is alive, otherwise false

wakeUpAttachment

public void wakeUpAttachment(Attachment att)
                      throws java.io.IOException,
                             EtException

Wake up an attachment that is waiting to read events from a station's empty input list.

Parameters:

att - attachment to wake up

Throws:

java.io.IOException - if problems with network comunications

EtException - if the attachment object is invalid

wakeUpAll

public void wakeUpAll(Station station)
               throws java.io.IOException,
                      EtException

Wake up all attachments waiting to read events from a station's empty input list.

Throws:

java.io.IOException - if problems with network comunications

EtException - if the station object is invalid

createStation

public Station createStation(StationConfig config,
                             java.lang.String name)
                      throws java.io.IOException,
                             EtException,
                             EtExistsException,
                             EtTooManyException

Creates a new station placed at the end of the linked list of stations. If the station is added to a group of parallel stations, it is placed at the end of the linked list of parallel stations.

Parameters:

config - station configuration

name - station name

Returns:

new station object

Throws:

java.io.IOException - if problems with network comunications

EtException - if the select method's class cannot be loaded, the position is less than 1 (GRAND_CENTRAL's spot), the name is GRAND_CENTRAL (already taken), the configuration's cue size is too big, or the configuration needs a select class name

EtExistsException - if the station already exists but with a different configuration

EtTooManyException - if the maximum number of stations has been created already

createStation

public Station createStation(StationConfig config,
                             java.lang.String name,
                             int position)
                      throws java.io.IOException,
                             EtException,
                             EtExistsException,
                             EtTooManyException

Creates a new station at a specified position in the linked list of stations. If the station is added to a group of parallel stations, it is placed at the end of the linked list of parallel stations.

Parameters:

config - station configuration

name - station name

Returns:

new station object

Throws:

java.io.IOException - if problems with network comunications

EtException - if the select method's class cannot be loaded, the position is less than 1 (GRAND_CENTRAL's spot), the name is GRAND_CENTRAL (already taken), the configuration's cue size is too big, or the configuration needs a select class name

EtExistsException - if the station already exists but with a different configuration

EtTooManyException - if the maximum number of stations has been created already

createStation

public Station createStation(StationConfig config,
                             java.lang.String name,
                             int position,
                             int parallelPosition)
                      throws java.io.IOException,
                             EtException,
                             EtExistsException,
                             EtTooManyException

Creates a new station at a specified position in the linked list of stations and in a specified position in a linked list of parallel stations if it is a parallel station.

Parameters:

config - station configuration

name - station name

position - position in the linked list to put the station.

Returns:

new station object

Throws:

java.io.IOException - if problems with network comunications

EtException - if the select method's class cannot be loaded, the position is less than 1 (GRAND_CENTRAL's spot), the name is GRAND_CENTRAL (already taken), the configuration's cue size is too big, or the configuration needs a select class name

EtExistsException - if the station already exists but with a different configuration

EtTooManyException - if the maximum number of stations has been created already

removeStation

public void removeStation(Station station)
                   throws java.io.IOException,
                          EtException

Removes an existing station.

Parameters:

station - station object

Throws:

java.io.IOException - if problems with network comunications

EtException - if attachments to the station still exist, the station is GRAND_CENTRAL (which must always exist), the station does not exist, or the station object is invalid

setStationPosition

public void setStationPosition(Station station,
                               int position,
                               int parallelPosition)
                        throws java.io.IOException,
                               EtException

Changes the position of a station in the linked list of stations.

Parameters:

station - station object

position - position in the main linked list (starting at 0)

Throws:

java.io.IOException - if problems with network comunications

EtException - if the station does not exist, trying to move GRAND_CENTRAL, position is < 1 (GRAND_CENTRAL is always first), parallelPosition < 0, station object is invalid, trying to move an incompatible parallel station to an existing group of parallel stations or to the head of an existing group of parallel stations.

getStationPosition

public int getStationPosition(Station station)
                       throws java.io.IOException,
                              EtException

Gets the position of a station in the linked list of stations.

Parameters:

station - station object

Returns:

position of a station in the main linked list of stations

Throws:

java.io.IOException - if problems with network comunications

EtException - if the station does not exist, or station object is invalid

getStationParallelPosition

public int getStationParallelPosition(Station station)
                               throws java.io.IOException,
                                      EtException

Gets the position of a parallel station in its linked list of parallel stations.

Parameters:

station - station object

Returns:

position of a station in the linked list of stations

Throws:

java.io.IOException - if problems with network comunications

EtException - if the station does not exist, or station object is invalid

attach

public Attachment attach(Station station)
                  throws java.io.IOException,
                         EtException,
                         EtTooManyException

Create an attachment to a station.

Parameters:

station - station object

Returns:

an attachment object

Throws:

java.io.IOException - if problems with network comunications

EtException - if the station does not exist, or station object is invalid

EtTooManyException - if no more attachments are allowed to the station, or if no more attachments are allowed to ET system

detach

public void detach(Attachment att)
            throws java.io.IOException,
                   EtException

Remove an attachment from a station.

Parameters:

att - attachment object

Throws:

java.io.IOException - if problems with network comunications

EtException - if the attachment object is invalid

stationAttached

public boolean stationAttached(Station station,
                               Attachment att)
                        throws java.io.IOException,
                               EtException

Tells if an attachment is attached to a station.

Parameters:

station - station object

att - attachment object

Returns:

true if an attachment is attached to a station and false otherwise

Throws:

java.io.IOException - if problems with network comunications

EtException - if the station does not exist, station object is invalid, or attachment object is invalid

stationExists

public boolean stationExists(java.lang.String name)
                      throws java.io.IOException

Tells if a station exists.

Parameters:

name - station name

Returns:

true if a station exists and false otherwise

Throws:

java.io.IOException - if problems with network comunications

stationNameToObject

public Station stationNameToObject(java.lang.String name)
                            throws java.io.IOException,
                                   EtException

Gets a station's object representation from its name.

Parameters:

name - station name

Returns:

station object

Throws:

java.io.IOException - if problems with network comunications

EtException - if the station does not exist

newEventsList

public java.util.ArrayList newEventsList(Attachment att,
                                         int mode,
                                         int microSec,
                                         int count,
                                         int size)
                                  throws java.io.IOException,
                                         EtException,
                                         EtEmptyException,
                                         EtBusyException,
                                         EtTimeoutException,
                                         EtWakeUpException

Get new or unused events from an ET system.

Parameters:

att - attachment object

mode - if there are no events available, this parameter specifies whether to wait for some by sleeping, by waiting for a set time, or by returning immediately

microSec - the number of microseconds to wait if a timed wait is specified

count - the number of events desired

size - the size of events in bytes

Returns:

an list of events

Throws:

java.io.IOException - if problems with network comunications

EtException - if arguments have bad values or attachment object is invalid

EtEmptyException - if the mode is asynchronous and the station's input list is empty

EtBusyException - if the mode is asynchronous and the station's input list is being used (the mutex is locked)

EtTimeoutException - if the mode is timed wait and the time has expired

EtWakeUpException - if the attachment has been commanded to wakeup, EventList.wakeUp(org.jlab.coda.et.AttachmentLocal), EventList.wakeUpAll()

newEvents

public Event[] newEvents(Attachment att,
                         int mode,
                         int microSec,
                         int count,
                         int size)
                  throws java.io.IOException,
                         EtException,
                         EtEmptyException,
                         EtBusyException,
                         EtTimeoutException,
                         EtWakeUpException

Get new or unused events from an ET system.

Parameters:

att - attachment object

mode - if there are no events available, this parameter specifies whether to wait for some by sleeping, by waiting for a set time, or by returning immediately

microSec - the number of microseconds to wait if a timed wait is specified

count - the number of events desired

size - the size of events in bytes

Returns:

an array of events

Throws:

java.io.IOException - if problems with network comunications

EtException - if arguments have bad values or attachment object is invalid

EtEmptyException - if the mode is asynchronous and the station's input list is empty

EtBusyException - if the mode is asynchronous and the station's input list is being used (the mutex is locked)

EtTimeoutException - if the mode is timed wait and the time has expired

EtWakeUpException - if the attachment has been commanded to wakeup, EventList.wakeUp(org.jlab.coda.et.AttachmentLocal), EventList.wakeUpAll()

getEventsList

public java.util.ArrayList getEventsList(Attachment att,
                                         int mode,
                                         int microSec,
                                         int count)
                                  throws java.io.IOException,
                                         EtException,
                                         EtEmptyException,
                                         EtBusyException,
                                         EtTimeoutException,
                                         EtWakeUpException

Get events from an ET system.

Parameters:

att - attachment object

mode - if there are no events available, this parameter specifies whether to wait for some by sleeping, by waiting for a set time, or by returning immediately

microSec - the number of microseconds to wait if a timed wait is specified

count - the number of events desired

Returns:

an list of events

Throws:

java.io.IOException - if problems with network comunications

EtException - if arguments have bad values, the attachment's station is GRAND_CENTRAL, or the attachment object is invalid

EtEmptyException - if the mode is asynchronous and the station's input list is empty

EtBusyException - if the mode is asynchronous and the station's input list is being used (the mutex is locked)

EtTimeoutException - if the mode is timed wait and the time has expired

EtWakeUpException - if the attachment has been commanded to wakeup, EventList.wakeUp(org.jlab.coda.et.AttachmentLocal), EventList.wakeUpAll()

getEvents

public Event[] getEvents(Attachment att,
                         int mode,
                         int microSec,
                         int count)
                  throws java.io.IOException,
                         EtException,
                         EtEmptyException,
                         EtBusyException,
                         EtTimeoutException,
                         EtWakeUpException

Get events from an ET system.

Parameters:

att - attachment object

mode - if there are no events available, this parameter specifies whether to wait for some by sleeping, by waiting for a set time, or by returning immediately

microSec - the number of microseconds to wait if a timed wait is specified

count - the number of events desired

Returns:

an array of events

Throws:

java.io.IOException - if problems with network comunications

EtException - if arguments have bad values, the attachment's station is GRAND_CENTRAL, or the attachment object is invalid

EtEmptyException - if the mode is asynchronous and the station's input list is empty

EtBusyException - if the mode is asynchronous and the station's input list is being used (the mutex is locked)

EtTimeoutException - if the mode is timed wait and the time has expired

EtWakeUpException - if the attachment has been commanded to wakeup, EventList.wakeUp(org.jlab.coda.et.AttachmentLocal), EventList.wakeUpAll()

getEvents2

public Event[] getEvents2(Attachment att,
                          int mode,
                          int microSec,
                          int count)
                   throws EtException,
                          EtEmptyException,
                          EtBusyException,
                          EtTimeoutException,
                          EtWakeUpException,
                          java.io.IOException

Get events from an ET system. Instead of using a buffered input stream, this method uses the socket's input stream and implements its own buffering scheme. This may or may not be faster than the getEvents method - depending on the JVM implementation. On Linux running Sun's 1.3 JVM, it's 20% faster than getEvents.

Parameters:

att - attachment object

mode - if there are no events available, this parameter specifies whether to wait for some by sleeping, by waiting for a set time, or by returning immediately

microSec - the number of microseconds to wait if a timed wait is specified

count - the number of events desired

Returns:

an array of events

Throws:

java.io.IOException - if problems with network comunications

EtException - if arguments have bad values, the attachment's station is GRAND_CENTRAL, or the attachment object is invalid

EtEmptyException - if the mode is asynchronous and the station's input list is empty

EtBusyException - if the mode is asynchronous and the station's input list is being used (the mutex is locked)

EtTimeoutException - if the mode is timed wait and the time has expired

EtWakeUpException - if the attachment has been commanded to wakeup, EventList.wakeUp(org.jlab.coda.et.AttachmentLocal), EventList.wakeUpAll()

putEventsList

public void putEventsList(Attachment att,
                          java.util.List eventList)
                   throws java.io.IOException,
                          EtException

Put events into an ET system.

Parameters:

att - attachment object

eventList - list of event objects

Throws:

java.io.IOException - if problems with network comunications

EtException - if events are not owned by this attachment or the attachment object is invalid

putEvents

public void putEvents(Attachment att,
                      Event[] evs)
               throws java.io.IOException,
                      EtException

Put events into an ET system.

Parameters:

att - attachment object

evs - array of event objects

Throws:

java.io.IOException - if problems with network comunications

EtException - if events are not owned by this attachment or the attachment object is invalid

putEvents2

public void putEvents2(Attachment att,
                       Event[] evs)
                throws java.io.IOException,
                       EtException

Put events into an ET system. Instead of using a buffered output stream, this method uses the socket's output stream and implements its own buffering scheme. This may or may not be faster than the putEvents method - depending on the JVM implementation.

Parameters:

att - attachment object

evs - array of event objects

Throws:

java.io.IOException - if problems with network comunications

EtException - if events are not owned by this attachment or the attachment object is invalid

dumpEventsList

public void dumpEventsList(Attachment att,
                           java.util.List eventList)
                    throws java.io.IOException,
                           EtException

Dispose of unwanted events in an ET system. The events are recycled and not made available to any other user.

Parameters:

att - attachment object

eventList - list of event objects

Throws:

java.io.IOException - if problems with network comunications

EtException - if events are not owned by this attachment or the attachment object is invalid

dumpEvents

public void dumpEvents(Attachment att,
                       Event[] evs)
                throws java.io.IOException,
                       EtException

Dispose of unwanted events in an ET system. The events are recycled and not made available to any other user.

Parameters:

att - attachment object

evs - array of event objects

Throws:

java.io.IOException - if problems with network comunications

EtException - if events are not owned by this attachment or the attachment object is invalid

getNumStations

public int getNumStations()
                   throws java.io.IOException

Gets the number of stations in the ET system.

Returns:

number of stations in the ET system

Throws:

java.io.IOException - if there are problems with network communication

getStationsMax

public int getStationsMax()
                   throws java.io.IOException

Gets the maximum number of stations allowed in the ET system.

Returns:

maximum number of stations allowed in the ET system

Throws:

java.io.IOException - if there are problems with network communication

getNumAttachments

public int getNumAttachments()
                      throws java.io.IOException

Gets the number of attachments in the ET system.

Returns:

number of attachments in the ET system

Throws:

java.io.IOException - if there are problems with network communication

getAttachmentsMax

public int getAttachmentsMax()
                      throws java.io.IOException

Gets the maximum number of attachments allowed in the ET system.

Returns:

maximum number of attachments allowed in the ET system

Throws:

java.io.IOException - if there are problems with network communication

getNumProcesses

public int getNumProcesses()
                    throws java.io.IOException

Gets the number of local processes in the ET system. This is only relevant in C-language, Solaris systems.

Returns:

number of processes in the ET system

Throws:

java.io.IOException - if there are problems with network communication

getProcessesMax

public int getProcessesMax()
                    throws java.io.IOException

Gets the maximum number of local processes allowed in the ET system. This is only relevant in C-language, Solaris systems.

Returns:

maximum number of processes allowed in the ET system

Throws:

java.io.IOException - if there are problems with network communication

getNumTemps

public int getNumTemps()
                throws java.io.IOException

Gets the number of temp events in the ET system. This is only relevant in C-language systems.

Returns:

number of temp events in the ET system

Throws:

java.io.IOException - if there are problems with network communication

getTempsMax

public int getTempsMax()
                throws java.io.IOException

Gets the maximum number of temp events allowed in the ET system. This is only relevant in C-language systems.

Returns:

maximum number of temp events in the ET system

Throws:

java.io.IOException - if there are problems with network communication

getHeartbeat

public int getHeartbeat()
                 throws java.io.IOException

Gets the ET system heartbeat. This is only relevant in C-language systems.

Returns:

ET system heartbeat

Throws:

java.io.IOException - if there are problems with network communication

getPid

public int getPid()
           throws java.io.IOException

Gets the UNIX pid of the ET system process. This is only relevant in C-language systems.

Returns:

UNIX pid of the ET system process

Throws:

java.io.IOException - if there are problems with network communication

getNumEvents

public int getNumEvents()

Gets the number of events in the ET system.

Returns:

number of events in the ET system

getEventSize

public int getEventSize()

Gets the "normal" event size in bytes.

Returns:

normal event size in bytes

getLanguage

public int getLanguage()

Gets the ET system's implementation language.

Returns:

ET system's implementation language

getHost

public java.lang.String getHost()

Gets the ET system's host name.

Returns:

ET system's host name

getTcpPort

public int getTcpPort()

Gets the tcp server port number.

Returns:

tcp server port number

getDebug

public int getDebug()

Gets the debug output level.

Returns:

debug output level

setDebug

public void setDebug(int val)
              throws EtException

Sets the debug output level. Must be either Constants.debugNone, Constants.debugSevere, Constants.debugError, Constants.debugWarn, or Constants.debugInfo.

Parameters:

val - debug level

Throws:

EtException - if bad argument value

getConfig

public SystemOpenConfig getConfig()

Gets a copy of the configuration used to specify how to open the ET system.

Returns:

SystemOpenConfig object used to specify how to open the ET system.

getData

public AllData getData()
                throws EtException,
                       java.io.IOException

Gets all information about the ET system.

Returns:

object containing ET system information

Throws:

java.io.IOException - if there are problems with network communication

EtException

getHistogram

public int[] getHistogram()
                   throws java.io.IOException,
                          EtException

Gets histogram containing data showing how many events in GRAND_CENTRAL's input list when new events are requested by users. This feature is not available on Java ET systems.

Returns:

integer array containing histogram

Throws:

java.io.IOException - if there are problems with network communication

EtException