nl.knmi.orfeus.seedlink.client
Class SeedLinkConnection

java.lang.Object
  extended by nl.knmi.orfeus.seedlink.client.SeedLinkConnection

public class SeedLinkConnection
extends java.lang.Object

Class to manage a connection to a SeedLink server using a Socket. See nl.knmi.orfeus.SLClient for an example of how to create and use this SeedLinkConnection object. A new SeedLink application can be created by subclassing SLClient, or by creating a new class and invoking the methods of SeedLinkConnection.

See Also:
SLClient, Socket

Field Summary
protected  java.lang.String begin_time
          Beginning of time window.
protected static int DFT_READBUF_SIZE
          Default size for buffer to hold responses from server.
protected  boolean dialup
          Flag to indicate dial-up mode.
protected  java.lang.String end_time
          End of time window.
protected  java.lang.String infoRequestString
          INFO level to request.
protected  java.lang.StringBuffer infoStrBuf
          String to store INFO packet contents.
protected  java.lang.String infoString
          String containing concatination of contents of last terminated set of INFO packets
protected  int keepalive
          Interval to send keepalive/heartbeat (seconds).
protected  boolean lastpkttime
          Flag to control last packet time usage.
protected  boolean multistation
          Flag to indicate multistation mode.
protected  int netdly
          Network reconnect delay (seconds).
protected  int netto
          Network timeout (seconds).
protected static char QUOTE_CHAR
          Character used for delimiting timestamp strings in the statefile.
protected  boolean resume
          Flag to control resuming with sequence numbers.
static java.lang.String SEEDLINK_PROTOCOL_PREFIX
          URI/URL prefix for seedlink servers ("seedlnk://")
protected  java.lang.String server_id
          ID of the remote SeedLink server.
protected  float server_version
          Version of the remote SeedLink server
protected  java.lang.String sladdr
          The host:port of the SeedLink server.
protected  SLLog sllog
          Logging object.
protected  java.net.Socket socket
          The network socket.
protected  java.io.InputStream socketInputStream
          The network socket InputStream.
protected  java.io.OutputStream socketOutputStream
          The network socket OutputStream.
protected  SLState state
          Persistent state information.
protected  java.lang.String statefile
          File name for storing state information.
protected  java.util.Vector streams
          Vector of SLNetStation objects.
protected  boolean terminateFlag
          Flag to control connection termination.
protected static java.lang.String UNINETWORK
          The network code used for uni-station mode
protected static java.lang.String UNISTATION
          The station code used for uni-station mode
 
Constructor Summary
SeedLinkConnection(SLLog sllog)
          Creates a new instance of SeedLinkConnection.
 
Method Summary
protected  int addStream(java.lang.String net, java.lang.String station, java.lang.String selectors, int seqnum, java.lang.String timestamp)
          Add a new stream entry to the stream chain for the given net/station parameters.
protected  void appendInfoString(SLPacket slpacket)
          Append the info String to the String Buffer.
protected  boolean checkslcd()
          Check this SeedLinkConnection description has valid parameters.
 int checkVersion(float version)
          Checks server version number against a given specified value.
 void close()
          Closes this SeedLinkConnection by closing the network socket and saving the state to the statefile, if it exists.
 SLPacket collect()
          Manage a connection to a SeedLink server based on the values given in this SeedLinkConnection, and to collect data.
 void configLink()
          Configure/negotiate data stream(s) with the remote SeedLink server.
 void connect()
          Open a network socket connection to a SeedLink server.
protected  java.lang.String createInfoString(java.lang.StringBuffer strBuf)
          Creates an info String from a String Buffer
 void disconnect()
          Close the network socket associated with this connection.
protected  SLPacket doTerminate()
           
 java.lang.String getInfoString()
          Returns the results of the last INFO request.
protected  int getInteger(edu.iris.Fissures.seed.container.Blockette blockette, int fieldNum)
          Get the integer value from the specified blockette field.
 int getKeepAlive()
          Returns the interval to send keepalive/heartbeat (seconds).
 SLLog getLog()
          Returns the SLLog logging object.
 int getNetDelay()
          Returns the network reconnect delay (seconds).
 int getNetTimout()
          Returns the network timeout (seconds).
 java.lang.String getSLAddress()
          Returns the host:port of the SeedLink server.
 SLState getState()
          Returns the SLState state object.
 java.util.Vector getStreams()
          Returns a copy of the Vector of SLNetStation objects.
 boolean isConnected()
          Returns connection state of the connection socket.
 void negotiateMultiStation()
          Negotiate a SeedLink connection using multi-station mode and issue the END action command.
 void negotiateStation(SLNetStation curstream)
          Negotiate a SeedLink connection for a single station and issue the DATA command.
 void negotiateUniStation()
          Negotiate a SeedLink connection in uni-station mode and issue the DATA command.
 int parseStreamlist(java.lang.String streamlist, java.lang.String defselect)
          Parse a string of streams and selectors and add them to the stream chain for configuring a multi-station connection.
 int readStreamList(java.lang.String streamfile, java.lang.String defselect)
          Read a list of streams and selectors from a file and add them to the stream chain for configuring a multi-station connection.
 byte[] receiveData(int maxbytes, java.lang.String code)
          Read bytes from the server.
 int recoverState(java.lang.String statefile)
          Recover the state file and put the sequence numbers and time stamps into the pre-existing stream chain entries.
 void requestInfo(java.lang.String infoLevel)
          Add an INFO request to the SeedLink Connection Description.
 int saveState(java.lang.String statefile)
          Save all current s equence numbers and time stamps into the given state file.
 void sayHello()
          Send the HELLO command and attempt to parse the server version number from the returned string.
 byte[] sendData(byte[] sendbytes, java.lang.String code, int resplen)
          Send bytes to the server.
 void sendInfoRequest(java.lang.String infoLevel, int verb_level)
          Sends a request for the specified INFO level.
 void setBeginTime(java.lang.String startTimeStr)
          Sets begin_time for initiation of continuous data transmission.
 void setEndTime(java.lang.String endTimeStr)
          Sets end_time for termitiation of data transmission.
 void setKeepAlive(int keepalive)
          Sets interval to send keepalive/heartbeat (seconds).
 void setLastpkttime(boolean lastpkttime)
          Sets a specified start time for beginning of data transmission .
 void setLog(SLLog sllog)
          Sets the SLLog logging object.
 void setNetDelay(int netdly)
          Sets the network reconnect delay (seconds).
 void setNetTimout(int netto)
          Sets the network timeout (seconds).
 void setSLAddress(java.lang.String sladdr)
          Sets the host:port of the SeedLink server.
 int setStateFile(java.lang.String statefile)
          Set the state file and recover state.
 void setUniParams(java.lang.String selectors, int seqnum, java.lang.String timestamp)
          Set the parameters for a uni-station mode connection for the given SLCD struct.
 void terminate()
          Sets terminate flag, closes connection and clears state as soon as possible
 void updateStream(SLPacket slpacket)
          Update the appropriate stream chain entry given a Mini-SEED record.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

SEEDLINK_PROTOCOL_PREFIX

public static final java.lang.String SEEDLINK_PROTOCOL_PREFIX
URI/URL prefix for seedlink servers ("seedlnk://")

See Also:
Constant Field Values

UNISTATION

protected static final java.lang.String UNISTATION
The station code used for uni-station mode

See Also:
Constant Field Values

UNINETWORK

protected static final java.lang.String UNINETWORK
The network code used for uni-station mode

See Also:
Constant Field Values

DFT_READBUF_SIZE

protected static final int DFT_READBUF_SIZE
Default size for buffer to hold responses from server.

See Also:
Constant Field Values

QUOTE_CHAR

protected static char QUOTE_CHAR
Character used for delimiting timestamp strings in the statefile.


sladdr

protected java.lang.String sladdr
The host:port of the SeedLink server.


keepalive

protected int keepalive
Interval to send keepalive/heartbeat (seconds).


netto

protected int netto
Network timeout (seconds).


netdly

protected int netdly
Network reconnect delay (seconds).


sllog

protected SLLog sllog
Logging object.


infoString

protected java.lang.String infoString
String containing concatination of contents of last terminated set of INFO packets


statefile

protected java.lang.String statefile
File name for storing state information.


lastpkttime

protected boolean lastpkttime
Flag to control last packet time usage. if true, begin_time is appended to DATA command


streams

protected java.util.Vector streams
Vector of SLNetStation objects.


begin_time

protected java.lang.String begin_time
Beginning of time window.


end_time

protected java.lang.String end_time
End of time window.


resume

protected boolean resume
Flag to control resuming with sequence numbers.


multistation

protected boolean multistation
Flag to indicate multistation mode.


dialup

protected boolean dialup
Flag to indicate dial-up mode.


terminateFlag

protected boolean terminateFlag
Flag to control connection termination.


server_id

protected java.lang.String server_id
ID of the remote SeedLink server.


server_version

protected float server_version
Version of the remote SeedLink server


infoRequestString

protected java.lang.String infoRequestString
INFO level to request.


socket

protected java.net.Socket socket
The network socket.


socketInputStream

protected java.io.InputStream socketInputStream
The network socket InputStream.


socketOutputStream

protected java.io.OutputStream socketOutputStream
The network socket OutputStream.


state

protected SLState state
Persistent state information.


infoStrBuf

protected java.lang.StringBuffer infoStrBuf
String to store INFO packet contents.

Constructor Detail

SeedLinkConnection

public SeedLinkConnection(SLLog sllog)
Creates a new instance of SeedLinkConnection.

Parameters:
sllog - an SLLoc object to control info and error message logging.
Method Detail

isConnected

public boolean isConnected()
Returns connection state of the connection socket.

Returns:
true if connected, false if not connected or socket is not initialized

getState

public SLState getState()
Returns the SLState state object.

Returns:
the SLState state object

setLog

public void setLog(SLLog sllog)
Sets the SLLog logging object.

Parameters:
sllog - an SLLoc object to control info and error message logging.

getLog

public SLLog getLog()
Returns the SLLog logging object.

Returns:
the SLLoc object to control info and error message logging.

setNetTimout

public void setNetTimout(int netto)
Sets the network timeout (seconds).

Parameters:
netto - the network timeout in seconds.

getNetTimout

public int getNetTimout()
Returns the network timeout (seconds).

Returns:
the network timeout in seconds.

setKeepAlive

public void setKeepAlive(int keepalive)
Sets interval to send keepalive/heartbeat (seconds).

Parameters:
keepalive - the interval to send keepalive/heartbeat in seconds.

getKeepAlive

public int getKeepAlive()
Returns the interval to send keepalive/heartbeat (seconds).

Returns:
the interval to send keepalive/heartbeat in seconds.

setNetDelay

public void setNetDelay(int netdly)
Sets the network reconnect delay (seconds).

Parameters:
netdly - the network reconnect delay in seconds.

getNetDelay

public int getNetDelay()
Returns the network reconnect delay (seconds).

Returns:
the network reconnect delay in seconds.

setSLAddress

public void setSLAddress(java.lang.String sladdr)
Sets the host:port of the SeedLink server.

Parameters:
sladdr - the host:port of the SeedLink server.

setLastpkttime

public void setLastpkttime(boolean lastpkttime)
Sets a specified start time for beginning of data transmission .

Parameters:
if - true, beginning time of last packet recieved for each station is appended to DATA command on resume.

setBeginTime

public void setBeginTime(java.lang.String startTimeStr)
Sets begin_time for initiation of continuous data transmission.

Parameters:
startTimeStr - start time in in SeedLink string format: "year,month,day,hour,minute,second".

setEndTime

public void setEndTime(java.lang.String endTimeStr)
Sets end_time for termitiation of data transmission.

Parameters:
endTimeStr - start time in in SeedLink string format: "year,month,day,hour,minute,second".

terminate

public void terminate()
Sets terminate flag, closes connection and clears state as soon as possible


getSLAddress

public java.lang.String getSLAddress()
Returns the host:port of the SeedLink server.

Returns:
the host:port of the SeedLink server.

getStreams

public java.util.Vector getStreams()
Returns a copy of the Vector of SLNetStation objects.

Returns:
a copy of the Vector of SLNetStation objects.

getInfoString

public java.lang.String getInfoString()
Returns the results of the last INFO request.

Returns:
concatination of contents of last terminated set of INFO packets

createInfoString

protected java.lang.String createInfoString(java.lang.StringBuffer strBuf)
Creates an info String from a String Buffer

Parameters:
strBuf - the buffer to convert to an INFO String.
Returns:
the INFO Sting.

checkslcd

protected boolean checkslcd()
Check this SeedLinkConnection description has valid parameters.

Returns:
true if pass and false if problems were identified.

readStreamList

public int readStreamList(java.lang.String streamfile,
                          java.lang.String defselect)
                   throws SeedLinkException
Read a list of streams and selectors from a file and add them to the stream chain for configuring a multi-station connection. If 'defselect' is not null it will be used as the default selectors for entries will no specific selectors indicated. The file is expected to be repeating lines of the form:
     [selectors]
 
For example:
 # Comment lines begin with a '#' or '*'
 GE ISP  BH?.D
 NL HGN
 MN AQU  BH?  HH?
 

Parameters:
streamfile - name of file containing list of streams and slectors.
defselect - default selectors.
Returns:
the number of streams configured.
Throws:
SeedLinkException - on error.

parseStreamlist

public int parseStreamlist(java.lang.String streamlist,
                           java.lang.String defselect)
                    throws SeedLinkException
Parse a string of streams and selectors and add them to the stream chain for configuring a multi-station connection. The string should be of the following form: "stream1[:selectors1],stream2[:selectors2],..." For example:
 "IU_KONO:BHE BHN,GE_WLF,MN_AQU:HH?.D"
 

Parameters:
streamlist - list of streams and slectors.
defselect - default selectors.
Returns:
the number of streams configured.
Throws:
SeedLinkException - on error.

addStream

protected int addStream(java.lang.String net,
                        java.lang.String station,
                        java.lang.String selectors,
                        int seqnum,
                        java.lang.String timestamp)
                 throws SeedLinkException
Add a new stream entry to the stream chain for the given net/station parameters. If the stream entry already exists do nothing and return 1. Also sets the multistation flag to true.

Parameters:
net - network code.
station - station code.
selectors - selectors for this net/station, null if none.
seqnum - SeedLink sequence number of last packet received, -1 to start at the next data.
timestamp - SeedLink time stamp in SEED "year,day-of-year,hour,minute,second" format for last packet received, null for none.
Returns:
0 if successfully added, 1 if an entry for network and station already exists.
Throws:
SeedLinkException - on error.

setUniParams

public void setUniParams(java.lang.String selectors,
                         int seqnum,
                         java.lang.String timestamp)
                  throws SeedLinkException
Set the parameters for a uni-station mode connection for the given SLCD struct. If the stream entry already exists, overwrite the previous settings. Also sets the multistation flag to 0 (false).

Parameters:
selectors - selectors for this net/station, null if none.
seqnum - SeedLink sequence number of last packet received, -1 to start at the next data.
timestamp - SeedLink time stamp in SEED "year,day-of-year,hour,minute,second" format for last packet received, null for none.
Throws:
SeedLinkException - on error.

setStateFile

public int setStateFile(java.lang.String statefile)
                 throws SeedLinkException
Set the state file and recover state.

Parameters:
statefile - path and name of statefile.
Returns:
the number of stream chains recovered.
Throws:
SeedLinkException - on error.

recoverState

public int recoverState(java.lang.String statefile)
                 throws SeedLinkException
Recover the state file and put the sequence numbers and time stamps into the pre-existing stream chain entries.

Parameters:
statefile - path and name of statefile.
Returns:
the number of stream chains recovered.
Throws:
SeedLinkException - on error.

saveState

public int saveState(java.lang.String statefile)
              throws SeedLinkException
Save all current s equence numbers and time stamps into the given state file.

Parameters:
statefile - path and name of statefile.
Returns:
the number of stream chains saved.
Throws:
SeedLinkException - on error.

doTerminate

protected SLPacket doTerminate()

collect

public SLPacket collect()
                 throws SeedLinkException
Manage a connection to a SeedLink server based on the values given in this SeedLinkConnection, and to collect data. Designed to run in a tight loop at the heart of a client program, this function will return every time a packet is received.

Returns:
an SLPacket when something is received.
Throws:
SeedLinkException - on error.

appendInfoString

protected void appendInfoString(SLPacket slpacket)
Append the info String to the String Buffer.

Parameters:
slpacket - the SeedLink packet.

getInteger

protected int getInteger(edu.iris.Fissures.seed.container.Blockette blockette,
                         int fieldNum)
                  throws edu.iris.Fissures.seed.exception.SeedException
Get the integer value from the specified blockette field.

Parameters:
blockette - the blockette.
fieldNum - the field number.
Returns:
the integer value.
Throws:
edu.iris.Fissures.seed.exception.SeedException - if error.

connect

public void connect()
             throws SeedLinkException,
                    java.io.IOException
Open a network socket connection to a SeedLink server. Expects sladdr to be in 'host:port' format.

Throws:
SeedLinkException - on error or no response or bad response from server.
java.io.IOException - if an I/O error occurs.

disconnect

public void disconnect()
Close the network socket associated with this connection.


close

public void close()
Closes this SeedLinkConnection by closing the network socket and saving the state to the statefile, if it exists.


sendData

public byte[] sendData(byte[] sendbytes,
                       java.lang.String code,
                       int resplen)
                throws SeedLinkException,
                       java.io.IOException
Send bytes to the server. This is only designed for small pieces of data, specifically for when the server responses to commands.

Parameters:
sendbytes - bytes to send.
code - a string to include in error messages for identification.
resplen - if > 0 then read up to resplen response bytes after sending.
Returns:
the response bytes or null if no response requested.
Throws:
SeedLinkException - on error or no response or bad response from server.
java.io.IOException - if an I/O error occurs.

receiveData

public byte[] receiveData(int maxbytes,
                          java.lang.String code)
                   throws java.io.IOException
Read bytes from the server.

Parameters:
maxbytes - maximum number of bytes to read.
code - a string to include in error messages for identification.
Returns:
the response bytes (zero length if no available data), or null if EOF.
Throws:
java.io.IOException - if an I/O error occurs.

sayHello

public void sayHello()
              throws SeedLinkException,
                     java.io.IOException
Send the HELLO command and attempt to parse the server version number from the returned string. The server version is set to 0.0 if it can not be parsed from the returned string.

Throws:
SeedLinkException - on error.
java.io.IOException - if an I/O error occurs.

requestInfo

public void requestInfo(java.lang.String infoLevel)
                 throws SeedLinkException
Add an INFO request to the SeedLink Connection Description.

Parameters:
infoLevel - the INFO level (one of: ID, STATIONS, STREAMS, GAPS, CONNECTIONS, ALL)
Throws:
SeedLinkException - if an INFO request is already pending.

sendInfoRequest

public void sendInfoRequest(java.lang.String infoLevel,
                            int verb_level)
                     throws SeedLinkException,
                            java.io.IOException
Sends a request for the specified INFO level. The verbosity level can be specified, allowing control of when the request should be logged.

Parameters:
infoLevel - the INFO level (one of: ID, STATIONS, STREAMS, GAPS, CONNECTIONS, ALL).
Throws:
SeedLinkException - on error.
java.io.IOException - if an I/O error occurs.

checkVersion

public int checkVersion(float version)
Checks server version number against a given specified value.

Parameters:
version - specified version value to test.
Returns:
1 if version is greater than or equal to value specified, 0 if no server version is known, -1 if version is less than value specified.

configLink

public void configLink()
                throws SeedLinkException,
                       java.io.IOException
Configure/negotiate data stream(s) with the remote SeedLink server. Negotiation will be either uni- or multi-station depending on the value of 'multistation' in this SeedLinkConnection.

Throws:
SeedLinkException - on error.
SeedLinkException - if multi-station and SeedLink version does not support multi-station protocol.
java.io.IOException

negotiateStation

public void negotiateStation(SLNetStation curstream)
                      throws SeedLinkException,
                             java.io.IOException
Negotiate a SeedLink connection for a single station and issue the DATA command. If selectors are defined, then the string is parsed on space and each selector is sent. If 'seqnum' != -1 and the SLCD 'resume' flag is true then data is requested starting at seqnum.

Parameters:
curstream - the description of the station to negotiate.
Throws:
SeedLinkException - on error.
java.io.IOException - if an I/O error occurs.

negotiateUniStation

public void negotiateUniStation()
                         throws SeedLinkException,
                                java.io.IOException
Negotiate a SeedLink connection in uni-station mode and issue the DATA command. This is compatible with SeedLink Protocol version 2 or greater. If selectors are defined, then the string is parsed on space and each selector is sent. If 'seqnum' != -1 and the SLCD 'resume' flag is true then data is requested starting at seqnum.

Throws:
SeedLinkException - on error.
java.io.IOException - if an I/O error occurs.

negotiateMultiStation

public void negotiateMultiStation()
                           throws SeedLinkException,
                                  java.io.IOException
Negotiate a SeedLink connection using multi-station mode and issue the END action command. This is compatible with SeedLink Protocol version 3, multi-station mode. If selectors are defined, then the string is parsed on space and each selector is sent. If 'seqnum' != -1 and the SLCD 'resume' flag is true then data is requested starting at seqnum.

Throws:
SeedLinkException - on error.
java.io.IOException - if an I/O error occurs.

updateStream

public void updateStream(SLPacket slpacket)
                  throws SeedLinkException
Update the appropriate stream chain entry given a Mini-SEED record.

Parameters:
slpacket - the packet containing a Mini-SEED record.
Throws:
SeedLinkException - on error.