Package edu.sc.seis.seisFile.seedlink

Class SeedlinkReader

  • public class SeedlinkReader
extends java.lang.Object
    Reader for the seedlink protocol in multistation mode. Protocol documentation can be found at seedlink Note this implementatino assumes multistation mode. It may be possible to use this in single station mode, but this has not been tested.

    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods 
      Modifier and Type Method Description
      boolean available()
      true if there is enough data in the instream to possibly read a data record.
      int availableBytes()
      Returns available() from the underlying InputStream, in bytes
      void close()  
      static boolean containsWildcard​(java.lang.String cmd)  
      static java.lang.String createResumeDataCommand​(java.lang.String lastNet, java.lang.String lastStation, SeedlinkState state)  
      void endHandshake()
      Ends the handshaking phase and starts data flowing.
      java.lang.String getHost()  
      java.lang.String getInfoString()
      Get the SeedLink information string for streams.
      java.lang.String getInfoString​(java.lang.String infoType)
      Get the SeedLink information string.
      java.lang.String getInfoString​(java.lang.String infoType, boolean addNewlines)
      Get the SeedLink information string.
      int getPort()  
      SeedlinkState getState()
      SeedlinkState is a utility object to allow the client to keep track of the last sequence number for each station and the sequence of commands that affect data that were sent to the server.
      java.io.PrintWriter getVerboseWriter()  
      boolean hasNext()
      Determine if a packet may be available.
      void info​(java.lang.String level)
      send an INFO command.
      protected void internalSendCmd​(java.lang.String cmd)  
      boolean isConnected()  
      boolean isVerbose()  
      SeedlinkPacket next()
      Get the next packet.
      static java.lang.String nextSeq​(java.lang.String seq)  
      protected java.lang.String readLine()  
      SeedlinkPacket readPacket()
      Read the next packet.
      void reconnect()
      Does a simple reconnect, replaying the original commands and restarting data.
      void restartData​(java.lang.String seqNum)
      Deprecated.
      use repeated selectData(String network, String station, List<String> locchan, int seqNum) followed by endHandshake()
      void resume()
      Deprecated.
      use resumeGlobalSequence
      static SeedlinkReader resume​(SeedlinkState seedlinkState, boolean verbose)
      Resumes the connection at the last successful packet using the sequence number.
      static SeedlinkReader resumeGlobalSequence​(SeedlinkState seedlinkState)  
      static SeedlinkReader resumeGlobalSequence​(SeedlinkState seedlinkState, boolean verbose)
      Resumes the connection at the last successful packet using the global last sequence number.
      void select​(java.lang.String network, java.lang.String station, java.lang.String location, java.lang.String channel)
      Deprecated.
      use selectData() or selectTime() instead
      void select​(java.lang.String network, java.lang.String station, java.lang.String location, java.lang.String channel, java.lang.String type)
      Deprecated.
      use selectData() or selectTime() instead
      void selectData​(java.lang.String network, java.lang.String station, java.util.List<java.lang.String> locchan)  
      void selectData​(java.lang.String network, java.lang.String station, java.util.List<java.lang.String> locchan, java.lang.String seqNum)  
      void selectData​(java.lang.String network, java.lang.String station, java.util.List<java.lang.String> locchan, java.time.Instant start)  
      void selectDataOfType​(java.lang.String network, java.lang.String station, java.util.List<java.lang.String> locchan, java.lang.String type)  
      void selectDataOfType​(java.lang.String network, java.lang.String station, java.util.List<java.lang.String> locchan, java.lang.String seqNum, java.lang.String type)  
      void selectDataOfType​(java.lang.String network, java.lang.String station, java.util.List<java.lang.String> locchan, java.time.Instant start, java.lang.String type)  
      void selectOfType​(java.lang.String network, java.lang.String station, java.util.List<java.lang.String> locchan, java.lang.String type)
      Deprecated.
      use selectData() or selectTime() instead
      void selectTime​(java.lang.String network, java.lang.String station, java.util.List<java.lang.String> locchan, java.time.Instant start)  
      void selectTime​(java.lang.String network, java.lang.String station, java.util.List<java.lang.String> locchan, java.time.Instant start, java.time.Instant end)  
      void selectTimeOfType​(java.lang.String network, java.lang.String station, java.util.List<java.lang.String> locchan, java.time.Instant start, java.time.Instant end, java.lang.String type)  
      void sendCmd​(java.lang.String cmd)
      Sends a SeedLink modifier command, generally should be limited to STATION, SELECT, FETCH, DATA and TIME.
      void sendData()  
      void sendData​(java.lang.String seqNum)  
      void sendData​(java.lang.String seqNum, java.time.Instant start)  
      void sendData​(java.time.Instant start)  
      java.lang.String[] sendHello()  
      void sendSelect​(java.lang.String locationChannel)
      Send a SELECT command for the given location-channel and with type of 'D'.
      void sendSelect​(java.lang.String locationChannel, java.lang.String type)
      Send a SELECT command for the given location-channel and type.
      void sendStation​(java.lang.String network, java.lang.String station)
      Send a STATION command for the given network and station.
      void sendTime​(java.time.Instant start)  
      void sendTime​(java.time.Instant start, java.time.Instant end)  
      void setVerbose​(boolean verbose)  
      void setVerboseWriter​(java.io.PrintWriter verboseWriter)  
      void startData()
      Deprecated.
      use repeated selectData() or selectTime() followed by endHandshake()
      void startData​(java.lang.String start, java.lang.String end)
      Deprecated.
      use repeated selectData() followed by endHandshake()
      void startData​(java.time.Instant start, java.time.Instant end)
      Deprecated.
      use repeated selectTime() followed by endHandshake()

      • Methods inherited from class java.lang.Object

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

    • Constructor Detail

      • SeedlinkReader

        public SeedlinkReader()
               throws java.io.IOException
        default of IRIS DMC
        Throws:
        java.io.IOException

      • SeedlinkReader

        public SeedlinkReader​(boolean verbose)
               throws java.io.IOException
        default of IRIS DMC
        Throws:
        java.io.IOException

      • SeedlinkReader

        public SeedlinkReader​(java.lang.String host)
               throws java.io.IOException
        uses the default port of 18000
        Throws:
        java.io.IOException

      • SeedlinkReader

        public SeedlinkReader​(java.lang.String host,
                      boolean verbose)
               throws java.io.IOException
        uses the default port of 18000
        Throws:
        java.io.IOException

      • SeedlinkReader

        public SeedlinkReader​(java.lang.String host,
                      int port)
               throws java.io.IOException
        Throws:
        java.io.IOException

      • SeedlinkReader

        public SeedlinkReader​(java.lang.String host,
                      int port,
                      boolean verbose)
               throws java.io.IOException
        Throws:
        java.io.IOException

      • SeedlinkReader

        public SeedlinkReader​(java.lang.String host,
                      int port,
                      int timeoutSeconds)
               throws java.io.IOException
        Throws:
        java.io.IOException

      • SeedlinkReader

        public SeedlinkReader​(java.lang.String host,
                      int port,
                      int timeoutSeconds,
                      boolean verbose)
               throws java.io.IOException
        Throws:
        java.io.IOException

      • SeedlinkReader

        public SeedlinkReader​(java.lang.String host,
                      int port,
                      int timeoutSeconds,
                      boolean verbose,
                      int connectTimeoutSeconds)
               throws java.io.IOException
        Throws:
        java.io.IOException

      • SeedlinkReader

        public SeedlinkReader​(SeedlinkState state,
                      int timeoutSeconds,
                      boolean verbose,
                      int connectTimeoutSeconds)

    • Method Detail

      • hasNext

        public boolean hasNext()
                throws java.io.IOException
        Determine if a packet may be available. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.
        Returns:
        true if a packet may be available, false if end was received.
        Throws:
        java.io.IOException - if an I/O Exception occurs.
        See Also:
        readPacket()

      • available

        public boolean available()
                  throws java.io.IOException
        true if there is enough data in the instream to possibly read a data record. This should not block, unlike hasNext() and next().
        Throws:
        java.io.IOException

      • availableBytes

        public int availableBytes()
                   throws java.io.IOException
        Returns available() from the underlying InputStream, in bytes
        Throws:
        java.io.IOException

      • getInfoString

        public java.lang.String getInfoString()
                               throws java.io.IOException,
                                      SeedlinkException,
                                      SeedFormatException
        Get the SeedLink information string for streams.
        Returns:
        the SeedLink information string or null if error.
        Throws:
        java.io.IOException - if an I/O Exception occurs.
        SeedlinkException - if no packets or there is an error creating the packet.
        SeedFormatException - if there is an error with the SEED format.

      • getInfoString

        public java.lang.String getInfoString​(java.lang.String infoType)
                               throws java.io.IOException,
                                      SeedlinkException,
                                      SeedFormatException
        Get the SeedLink information string.
        Parameters:
        infoType - the information type.
        Returns:
        the SeedLink information string or null if error.
        Throws:
        java.io.IOException - if an I/O Exception occurs.
        SeedlinkException - if no packets or there is an error creating the packet.
        SeedFormatException - if there is an error with the SEED format.

      • getInfoString

        public java.lang.String getInfoString​(java.lang.String infoType,
                                      boolean addNewlines)
                               throws java.io.IOException,
                                      SeedlinkException,
                                      SeedFormatException
        Get the SeedLink information string.
        Parameters:
        infoType - the information type.
        addNewlines - true to add newlines to support XML parsing, false otherwise.
        Returns:
        the SeedLink information string or null if error.
        Throws:
        java.io.IOException - if an I/O Exception occurs.
        SeedlinkException - if no packets or there is an error creating the packet.
        SeedFormatException - if there is an error with the SEED format.

      • next

        public SeedlinkPacket next()
                    throws java.io.IOException,
                           SeedlinkException
        Get the next packet. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.
        Returns:
        the packet or null if none.
        Throws:
        java.io.IOException - if an I/O Exception occurs.
        SeedlinkException - if no packets or there is an error creating the packet.
        See Also:
        hasNext(), readPacket()

      • readPacket

        public SeedlinkPacket readPacket()
                          throws java.io.IOException,
                                 SeedlinkException
        Read the next packet. This method should be called after calling the 'hasNext' method. This method blocks until input data is available, the end of the stream is detected, or an exception is thrown.
        Returns:
        the next packet.
        Throws:
        java.io.IOException - if an I/O Exception occurs.
        SeedlinkException - if there is an error creating the packet.
        See Also:
        hasNext()

      • info

        public void info​(java.lang.String level)
          throws java.io.IOException
        send an INFO command. The resulting packets can be retrieved with calls to next(), checking isInfoContinuesPacket() to see if more packets will be returned. INFO requests should probably not be sent after the end of the handshake as real data packets may arrive causing confusion. GetInfoString() is preferred as it iterates over all returned packets and returns the result as a single String.
        Throws:
        java.io.IOException

      • endHandshake

        public void endHandshake()
                  throws java.io.IOException
        Ends the handshaking phase and starts data flowing.
        Throws:
        java.io.IOException

      • close

        public void close()

      • isConnected

        public boolean isConnected()

      • reconnect

        public void reconnect()
               throws java.io.IOException,
                      SeedlinkException
        Does a simple reconnect, replaying the original commands and restarting data. This does not resume from the last packet, so data may be lost that arrived during the outage. See resume to reconnect and resume data flow from the last successful packet.
        Throws:
        java.io.IOException
        SeedlinkException

      • resume

        @Deprecated
public void resume()
            throws java.io.IOException,
                   SeedlinkException
        Deprecated.
        use resumeGlobalSequence
        Resumes the connection at the last successful packet using the global last sequence number. Note that this assumes that sequence numbers are global, not per station. Each DATA or TIME command in the original command sequence is replaced with 'DATA seq' to restart with the last received sequence number. If the server uses per station sequence numbering then the client must keep track of sequence numbers and use resume(SeedlinkState) to supply the sequence numbers.
        Throws:
        java.io.IOException
        SeedlinkException

      • resumeGlobalSequence

        public static SeedlinkReader resumeGlobalSequence​(SeedlinkState seedlinkState,
                                                  boolean verbose)
                                           throws java.io.IOException,
                                                  SeedlinkException
        Resumes the connection at the last successful packet using the global last sequence number. Note that this assumes that sequence numbers are global, not per station. Each DATA or TIME command in the original command sequence is replaced with 'DATA seq' to restart with the last received sequence number, which should work with wildcards.. If the server uses per station sequence numbering then the client must keep track of sequence numbers and use resume(SeedlinkState) to supply the sequence numbers, possibly with custom commands to handle wildcards.
        Throws:
        java.io.IOException
        SeedlinkException

      • resume

        public static SeedlinkReader resume​(SeedlinkState seedlinkState,
                                    boolean verbose)
                             throws java.io.IOException,
                                    SeedlinkException
        Resumes the connection at the last successful packet using the sequence number. Note that this uses a supplied per station last seq number. The map key is of the form NN.SSSSS where NN is the network code and SSSSS is the station code. It is also assumed that there is a DATA or TIME command in the original handshaking phase after each STATION command. Some servers allow multiple STATION commands before a DATA command, but this breaks restarting each station at the last sequence. The caller should call endHandshake() after creationg in order to begin data flow. This does not function correctly if wildcards have been used in the original request as there is no guarantee that all stations/channels that might match the wildcards have actually been seen before the interruption, and so the wildcard commands may need to be repeated. Resuming after STATION comamnds with wildcards should be handled externally by the client.
        Throws:
        java.io.IOException
        SeedlinkException

      • createResumeDataCommand

        public static java.lang.String createResumeDataCommand​(java.lang.String lastNet,
                                                       java.lang.String lastStation,
                                                       SeedlinkState state)

      • nextSeq

        public static java.lang.String nextSeq​(java.lang.String seq)

      • containsWildcard

        public static boolean containsWildcard​(java.lang.String cmd)

      • sendCmd

        public void sendCmd​(java.lang.String cmd)
             throws java.io.IOException,
                    SeedlinkException
        Sends a SeedLink modifier command, generally should be limited to STATION, SELECT, FETCH, DATA and TIME.
        Parameters:
        cmd - the command.
        Throws:
        SeedlinkException - if a SeedLink error occurs.
        java.io.IOException - if an I/O Exception occurs.

      • select

        @Deprecated
public void select​(java.lang.String network,
                   java.lang.String station,
                   java.lang.String location,
                   java.lang.String channel)
            throws SeedlinkException,
                   java.io.IOException
        Deprecated.
        use selectData() or selectTime() instead
        Select the stream. This sends a STATION followed by a SELECT command.
        Parameters:
        network - the network.
        station - the station.
        location - the location or empty if none.
        channel - the channel.
        Throws:
        SeedlinkException - if a SeedLink error occurs.
        java.io.IOException - if an I/O Exception occurs.

      • selectData

        public void selectData​(java.lang.String network,
                       java.lang.String station,
                       java.util.List<java.lang.String> locchan)
                throws SeedlinkException,
                       java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • selectOfType

        @Deprecated
public void selectOfType​(java.lang.String network,
                         java.lang.String station,
                         java.util.List<java.lang.String> locchan,
                         java.lang.String type)
                  throws SeedlinkException,
                         java.io.IOException
        Deprecated.
        use selectData() or selectTime() instead
        Utility function to select the stream. This sends a STATION followed by a SELECT command.
        Parameters:
        network - the network.
        station - the station.
        locchan - list of location channel.
        type - the data type.
        Throws:
        SeedlinkException
        java.io.IOException

      • selectDataOfType

        public void selectDataOfType​(java.lang.String network,
                             java.lang.String station,
                             java.util.List<java.lang.String> locchan,
                             java.lang.String type)
                      throws SeedlinkException,
                             java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • selectData

        public void selectData​(java.lang.String network,
                       java.lang.String station,
                       java.util.List<java.lang.String> locchan,
                       java.lang.String seqNum)
                throws SeedlinkException,
                       java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • selectDataOfType

        public void selectDataOfType​(java.lang.String network,
                             java.lang.String station,
                             java.util.List<java.lang.String> locchan,
                             java.lang.String seqNum,
                             java.lang.String type)
                      throws SeedlinkException,
                             java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • selectData

        public void selectData​(java.lang.String network,
                       java.lang.String station,
                       java.util.List<java.lang.String> locchan,
                       java.time.Instant start)
                throws SeedlinkException,
                       java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • selectDataOfType

        public void selectDataOfType​(java.lang.String network,
                             java.lang.String station,
                             java.util.List<java.lang.String> locchan,
                             java.time.Instant start,
                             java.lang.String type)
                      throws SeedlinkException,
                             java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • selectTime

        public void selectTime​(java.lang.String network,
                       java.lang.String station,
                       java.util.List<java.lang.String> locchan,
                       java.time.Instant start)
                throws SeedlinkException,
                       java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • selectTime

        public void selectTime​(java.lang.String network,
                       java.lang.String station,
                       java.util.List<java.lang.String> locchan,
                       java.time.Instant start,
                       java.time.Instant end)
                throws SeedlinkException,
                       java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • selectTimeOfType

        public void selectTimeOfType​(java.lang.String network,
                             java.lang.String station,
                             java.util.List<java.lang.String> locchan,
                             java.time.Instant start,
                             java.time.Instant end,
                             java.lang.String type)
                      throws SeedlinkException,
                             java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • select

        @Deprecated
public void select​(java.lang.String network,
                   java.lang.String station,
                   java.lang.String location,
                   java.lang.String channel,
                   java.lang.String type)
            throws SeedlinkException,
                   java.io.IOException
        Deprecated.
        use selectData() or selectTime() instead
        Utility function to select the stream. This sends a STATION followed by a SELECT command.
        Parameters:
        network - the network.
        station - the station.
        location - the location or empty if none.
        channel - the channel.
        type - the data type.
        Throws:
        SeedlinkException
        java.io.IOException

      • sendStation

        public void sendStation​(java.lang.String network,
                        java.lang.String station)
                 throws SeedlinkException,
                        java.io.IOException
        Send a STATION command for the given network and station. If either is length zero, a wildcard of "*" is inserted in its place. In the Seedlink protocol, a STATION command should be followed by one or more SELECT commands. See sendSelect().
        Parameters:
        network - the network.
        station - the station.
        Throws:
        SeedlinkException
        java.io.IOException

      • sendSelect

        public void sendSelect​(java.lang.String locationChannel)
                throws SeedlinkException,
                       java.io.IOException
        Send a SELECT command for the given location-channel and with type of 'D'. In the Seedlink protocol, a STATION command should be followed by one or more SELECT commands. See sendStation().
        Parameters:
        locationChannel - the combined location and channel, eg 00HHZ.
        Throws:
        SeedlinkException
        java.io.IOException

      • sendSelect

        public void sendSelect​(java.lang.String locationChannel,
                       java.lang.String type)
                throws SeedlinkException,
                       java.io.IOException
        Send a SELECT command for the given location-channel and type. In the Seedlink protocol, one or more SELECT commands should follow a STATION command. See sendStation().
        Parameters:
        locationChannel - the combined location and channel, eg 00HHZ.
        type - the data type.
        Throws:
        SeedlinkException
        java.io.IOException

      • startData

        @Deprecated
public void startData()
               throws SeedlinkException,
                      java.io.IOException
        Deprecated.
        use repeated selectData() or selectTime() followed by endHandshake()
        Start the data transfer.
        Throws:
        SeedlinkException - if a SeedLink error occurs.
        java.io.IOException - if an I/O Exception occurs.

      • startData

        @Deprecated
public void startData​(java.time.Instant start,
                      java.time.Instant end)
               throws SeedlinkException,
                      java.io.IOException
        Deprecated.
        use repeated selectTime() followed by endHandshake()
        Start the data transfer. Note the DMC only goes back 48 hours. The start and end time format is year,month,day,hour,minute,second, e.g. '2002,08,05,14,00'.
        Parameters:
        start - the start time or null if none.
        end - the end time or null if none (ignored if no start time.)
        Throws:
        SeedlinkException - if a SeedLink error occurs.
        java.io.IOException - if an I/O Exception occurs.

      • startData

        @Deprecated
public void startData​(java.lang.String start,
                      java.lang.String end)
               throws SeedlinkException,
                      java.io.IOException
        Deprecated.
        use repeated selectData() followed by endHandshake()
        Start the data transfer. Note the DMC only goes back 48 hours. The start and end time format is year,month,day,hour,minute,second, e.g. '2002,08,05,14,00'.
        Parameters:
        start - the start time or empty string if none.
        end - the end time or empty string if none (ignored if no start time.)
        Throws:
        SeedlinkException - if a SeedLink error occurs.
        java.io.IOException - if an I/O Exception occurs.

      • sendData

        public void sendData​(java.lang.String seqNum,
                     java.time.Instant start)
              throws SeedlinkException,
                     java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • sendTime

        public void sendTime​(java.time.Instant start,
                     java.time.Instant end)
              throws SeedlinkException,
                     java.io.IOException
        Throws:
        SeedlinkException
        java.io.IOException

      • restartData

        @Deprecated
public void restartData​(java.lang.String seqNum)
                 throws SeedlinkException,
                        java.io.IOException
        Deprecated.
        use repeated selectData(String network, String station, List<String> locchan, int seqNum) followed by endHandshake()
        Parameters:
        seqNum -
        Throws:
        SeedlinkException
        java.io.IOException

      • isVerbose

        public boolean isVerbose()

      • setVerbose

        public void setVerbose​(boolean verbose)

      • getVerboseWriter

        public java.io.PrintWriter getVerboseWriter()

      • setVerboseWriter

        public void setVerboseWriter​(java.io.PrintWriter verboseWriter)

      • getHost

        public java.lang.String getHost()

      • getPort

        public int getPort()

      • getState

        public SeedlinkState getState()
        SeedlinkState is a utility object to allow the client to keep track of the last sequence number for each station and the sequence of commands that affect data that were sent to the server. SeedlinkReader does not automatically keep track of these per station sequence numbers as it requires parsing the miniseed records. Clients that desire this should call SeedlinkState.update(SeedlinkPacket) to update the per station sequence number.