Package com.pixelmed.network

## Class StorageSOPClassSCPDispatcher

- java.lang.Object
- - com.pixelmed.network.StorageSOPClassSCPDispatcher

- All Implemented Interfaces:
    `java.lang.Runnable`

      public class StorageSOPClassSCPDispatcher
      extends java.lang.Object
      implements java.lang.Runnable

  This class waits for incoming connections and association requests for the SCP role of SOP Classes of the Storage Service Class, the Study Root Query Retrieve Information Model Find, Get and Move SOP Classes, and the Verification SOP Class.

  The class has a constructor and a `run()` method. The constructor is passed a socket on which to listen for transport connection open indications. The `run()` method waits for transport connection open indications, then instantiates `StorageSOPClassSCP` to accept an association and wait for storage or verification commands, storing data sets in Part 10 files in the specified folder.

  An instance of `ReceivedObjectHandler` can be supplied in the constructor to process the received data set stored in the file when it has been completely received.

  For example:

      try {
        new Thread(new StorageSOPClassSCPDispatcher(104,"STORESCP",new File("/tmp"),new OurReceivedObjectHandler(),0)).start();
      }
      catch (IOException e) {
        e.printStackTrace(System.err);
      }

  If it is necessary to shutdown the StorageSOPClassSCPDispatcher, for example after changing the properties that define the listening port or AE Title, the `shutdown()` method can be called.

  Debugging messages with a varying degree of verbosity can be activated.

  The main method is also useful in its own right as a command-line Storage SCP utility, which will store incoming files in a specified directory.

  For example, on Unix:

      % java -cp ./pixelmed.jar com.pixelmed.network.StorageSOPClassSCPDispatcher "104" "STORESCP" "/tmp" 0

  On Windows, the classpath syntax would use a different separator, e.g. `.\pixelmed.jar`

  Note that the main method can also be used without command line arguments, in which case it looks for a properties file or uses defaults (refer to the main() method documentation for details).

  See Also:
    `StorageSOPClassSCP`, `ReceivedObjectHandler`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `protected StoredFilePathStrategy` | `storedFilePathStrategy` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---

    `StorageSOPClassSCPDispatcher​(int port, java.lang.String calledAETitle, int ourMaximumLengthReceived, int socketReceiveBufferSize, int socketSendBufferSize, java.io.File savedImagesFolder, StoredFilePathStrategy storedFilePathStrategy, ReceivedObjectHandler receivedObjectHandler, QueryResponseGeneratorFactory queryResponseGeneratorFactory, RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory, NetworkApplicationInformation networkApplicationInformation, boolean secureTransport, int debugLevel)`

    Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

    `StorageSOPClassSCPDispatcher​(int port, java.lang.String calledAETitle, int ourMaximumLengthReceived, int socketReceiveBufferSize, int socketSendBufferSize, java.io.File savedImagesFolder, ReceivedObjectHandler receivedObjectHandler, QueryResponseGeneratorFactory queryResponseGeneratorFactory, RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory, NetworkApplicationInformation networkApplicationInformation, boolean secureTransport, int debugLevel)`

    Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

    `StorageSOPClassSCPDispatcher​(int port, java.lang.String calledAETitle, java.io.File savedImagesFolder, StoredFilePathStrategy storedFilePathStrategy, ReceivedObjectHandler receivedObjectHandler, int debugLevel)` | Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

    `StorageSOPClassSCPDispatcher​(int port, java.lang.String calledAETitle, java.io.File savedImagesFolder, StoredFilePathStrategy storedFilePathStrategy, ReceivedObjectHandler receivedObjectHandler, AssociationStatusHandler associationStatusHandler, QueryResponseGeneratorFactory queryResponseGeneratorFactory, RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory, NetworkApplicationInformation networkApplicationInformation, PresentationContextSelectionPolicy presentationContextSelectionPolicy, boolean secureTransport, int debugLevel)`

    Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

    `StorageSOPClassSCPDispatcher​(int port, java.lang.String calledAETitle, java.io.File savedImagesFolder, StoredFilePathStrategy storedFilePathStrategy, ReceivedObjectHandler receivedObjectHandler, QueryResponseGeneratorFactory queryResponseGeneratorFactory, RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory, NetworkApplicationInformation networkApplicationInformation, boolean secureTransport, int debugLevel)`

    Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

    `StorageSOPClassSCPDispatcher​(int port, java.lang.String calledAETitle, java.io.File savedImagesFolder, StoredFilePathStrategy storedFilePathStrategy, ReceivedObjectHandler receivedObjectHandler, QueryResponseGeneratorFactory queryResponseGeneratorFactory, RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory, NetworkApplicationInformation networkApplicationInformation, PresentationContextSelectionPolicy presentationContextSelectionPolicy, boolean secureTransport, int debugLevel)`

    Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

    `StorageSOPClassSCPDispatcher​(int port, java.lang.String calledAETitle, java.io.File savedImagesFolder, ReceivedObjectHandler receivedObjectHandler, int debugLevel)` | Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

    `StorageSOPClassSCPDispatcher​(int port, java.lang.String calledAETitle, java.io.File savedImagesFolder, ReceivedObjectHandler receivedObjectHandler, QueryResponseGeneratorFactory queryResponseGeneratorFactory, RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory, NetworkApplicationInformation networkApplicationInformation, boolean secureTransport, int debugLevel)`

    Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `isReady()` | Is the dispatcher ready to receive connections?
    `static void` | `main​(java.lang.String[] arg)` | For testing.
    `void` | `run()` | Waits for a transport connection indications, then spawns new threads to act as association acceptors, which then wait for storage or verification commands, storing data sets in Part 10 files in the specified folder, until the associations are released or the transport connections are closed.
    `void` | `shutdown()` | Request the dispatcher to stop listening and exit the thread.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### storedFilePathStrategy

          protected StoredFilePathStrategy storedFilePathStrategy

  - ### Constructor Detail

    - #### StorageSOPClassSCPDispatcher

          public StorageSOPClassSCPDispatcher​(int port,
                                              java.lang.String calledAETitle,
                                              java.io.File savedImagesFolder,
                                              ReceivedObjectHandler receivedObjectHandler,
                                              int debugLevel)
                                       throws java.io.IOException

      Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

      Parameters:
        `port` - the port on which to listen for connections
        `calledAETitle` - our AE Title
        `savedImagesFolder` - the folder in which to store received data sets (may be null, to ignore received data for testing)
        `receivedObjectHandler` - the handler to call after each data set has been received and stored
        `debugLevel` - zero for no debugging messages, higher values more verbose messages
      Throws:
        `java.io.IOException`

    - #### StorageSOPClassSCPDispatcher

          public StorageSOPClassSCPDispatcher​(int port,
                                              java.lang.String calledAETitle,
                                              java.io.File savedImagesFolder,
                                              StoredFilePathStrategy storedFilePathStrategy,
                                              ReceivedObjectHandler receivedObjectHandler,
                                              int debugLevel)
                                       throws java.io.IOException

      Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

      Parameters:
        `port` - the port on which to listen for connections
        `calledAETitle` - our AE Title
        `savedImagesFolder` - the folder in which to store received data sets (may be null, to ignore received data for testing)
        `storedFilePathStrategy` - the strategy to use for naming received files and folders
        `receivedObjectHandler` - the handler to call after each data set has been received and stored
        `debugLevel` - zero for no debugging messages, higher values more verbose messages
      Throws:
        `java.io.IOException`

    - #### StorageSOPClassSCPDispatcher

          public StorageSOPClassSCPDispatcher​(int port,
                                              java.lang.String calledAETitle,
                                              int ourMaximumLengthReceived,
                                              int socketReceiveBufferSize,
                                              int socketSendBufferSize,
                                              java.io.File savedImagesFolder,
                                              ReceivedObjectHandler receivedObjectHandler,
                                              QueryResponseGeneratorFactory queryResponseGeneratorFactory,
                                              RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory,
                                              NetworkApplicationInformation networkApplicationInformation,
                                              boolean secureTransport,
                                              int debugLevel)
                                       throws java.io.IOException

      Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

      Parameters:
        `port` - the port on which to listen for connections
        `calledAETitle` - our AE Title
        `ourMaximumLengthReceived` - the maximum PDU length that we will offer to receive
        `socketReceiveBufferSize` - the TCP socket receive buffer size to set (if possible), 0 means leave at the default
        `socketSendBufferSize` - the TCP socket send buffer size to set (if possible), 0 means leave at the default
        `savedImagesFolder` - the folder in which to store received data sets (may be null, to ignore received data for testing)
        `receivedObjectHandler` - the handler to call after each data set has been received and stored, or null for the default that prints the file name
        `queryResponseGeneratorFactory` - the factory to make handlers to generate query responses from a supplied query message
        `retrieveResponseGeneratorFactory` - the factory to make handlers to generate retrieve responses from a supplied retrieve message
        `networkApplicationInformation` - from which to obtain a map of application entity titles to presentation addresses
        `secureTransport` - true if to use secure transport protocol
        `debugLevel` - zero for no debugging messages, higher values more verbose messages
      Throws:
        `java.io.IOException`

    - #### StorageSOPClassSCPDispatcher

          public StorageSOPClassSCPDispatcher​(int port,
                                              java.lang.String calledAETitle,
                                              int ourMaximumLengthReceived,
                                              int socketReceiveBufferSize,
                                              int socketSendBufferSize,
                                              java.io.File savedImagesFolder,
                                              StoredFilePathStrategy storedFilePathStrategy,
                                              ReceivedObjectHandler receivedObjectHandler,
                                              QueryResponseGeneratorFactory queryResponseGeneratorFactory,
                                              RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory,
                                              NetworkApplicationInformation networkApplicationInformation,
                                              boolean secureTransport,
                                              int debugLevel)
                                       throws java.io.IOException

      Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

      Parameters:
        `port` - the port on which to listen for connections
        `calledAETitle` - our AE Title
        `ourMaximumLengthReceived` - the maximum PDU length that we will offer to receive
        `socketReceiveBufferSize` - the TCP socket receive buffer size to set (if possible), 0 means leave at the default
        `socketSendBufferSize` - the TCP socket send buffer size to set (if possible), 0 means leave at the default
        `savedImagesFolder` - the folder in which to store received data sets (may be null, to ignore received data for testing)
        `storedFilePathStrategy` - the strategy to use for naming received files and folders
        `receivedObjectHandler` - the handler to call after each data set has been received and stored, or null for the default that prints the file name
        `queryResponseGeneratorFactory` - the factory to make handlers to generate query responses from a supplied query message
        `retrieveResponseGeneratorFactory` - the factory to make handlers to generate retrieve responses from a supplied retrieve message
        `networkApplicationInformation` - from which to obtain a map of application entity titles to presentation addresses
        `secureTransport` - true if to use secure transport protocol
        `debugLevel` - zero for no debugging messages, higher values more verbose messages
      Throws:
        `java.io.IOException`

    - #### StorageSOPClassSCPDispatcher

          public StorageSOPClassSCPDispatcher​(int port,
                                              java.lang.String calledAETitle,
                                              java.io.File savedImagesFolder,
                                              ReceivedObjectHandler receivedObjectHandler,
                                              QueryResponseGeneratorFactory queryResponseGeneratorFactory,
                                              RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory,
                                              NetworkApplicationInformation networkApplicationInformation,
                                              boolean secureTransport,
                                              int debugLevel)
                                       throws java.io.IOException

      Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

      Parameters:
        `port` - the port on which to listen for connections
        `calledAETitle` - our AE Title
        `savedImagesFolder` - the folder in which to store received data sets (may be null, to ignore received data for testing)
        `receivedObjectHandler` - the handler to call after each data set has been received and stored, or null for the default that prints the file name
        `queryResponseGeneratorFactory` - the factory to make handlers to generate query responses from a supplied query message
        `retrieveResponseGeneratorFactory` - the factory to make handlers to generate retrieve responses from a supplied retrieve message
        `networkApplicationInformation` - from which to obtain a map of application entity titles to presentation addresses
        `secureTransport` - true if to use secure transport protocol
        `debugLevel` - zero for no debugging messages, higher values more verbose messages
      Throws:
        `java.io.IOException`

    - #### StorageSOPClassSCPDispatcher

          public StorageSOPClassSCPDispatcher​(int port,
                                              java.lang.String calledAETitle,
                                              java.io.File savedImagesFolder,
                                              StoredFilePathStrategy storedFilePathStrategy,
                                              ReceivedObjectHandler receivedObjectHandler,
                                              QueryResponseGeneratorFactory queryResponseGeneratorFactory,
                                              RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory,
                                              NetworkApplicationInformation networkApplicationInformation,
                                              boolean secureTransport,
                                              int debugLevel)
                                       throws java.io.IOException

      Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

      Parameters:
        `port` - the port on which to listen for connections
        `calledAETitle` - our AE Title
        `savedImagesFolder` - the folder in which to store received data sets (may be null, to ignore received data for testing)
        `storedFilePathStrategy` - the strategy to use for naming received files and folders, or null for the default
        `receivedObjectHandler` - the handler to call after each data set has been received and stored, or null for the default that prints the file name
        `queryResponseGeneratorFactory` - the factory to make handlers to generate query responses from a supplied query message
        `retrieveResponseGeneratorFactory` - the factory to make handlers to generate retrieve responses from a supplied retrieve message
        `networkApplicationInformation` - from which to obtain a map of application entity titles to presentation addresses
        `secureTransport` - true if to use secure transport protocol
        `debugLevel` - zero for no debugging messages, higher values more verbose messages
      Throws:
        `java.io.IOException`

    - #### StorageSOPClassSCPDispatcher

          public StorageSOPClassSCPDispatcher​(int port,
                                              java.lang.String calledAETitle,
                                              java.io.File savedImagesFolder,
                                              StoredFilePathStrategy storedFilePathStrategy,
                                              ReceivedObjectHandler receivedObjectHandler,
                                              QueryResponseGeneratorFactory queryResponseGeneratorFactory,
                                              RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory,
                                              NetworkApplicationInformation networkApplicationInformation,
                                              PresentationContextSelectionPolicy presentationContextSelectionPolicy,
                                              boolean secureTransport,
                                              int debugLevel)
                                       throws java.io.IOException

      Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

      Parameters:
        `port` - the port on which to listen for connections
        `calledAETitle` - our AE Title
        `savedImagesFolder` - the folder in which to store received data sets (may be null, to ignore received data for testing)
        `storedFilePathStrategy` - the strategy to use for naming received files and folders, or null for the default
        `receivedObjectHandler` - the handler to call after each data set has been received and stored, or null for the default that prints the file name
        `queryResponseGeneratorFactory` - the factory to make handlers to generate query responses from a supplied query message
        `retrieveResponseGeneratorFactory` - the factory to make handlers to generate retrieve responses from a supplied retrieve message
        `networkApplicationInformation` - from which to obtain a map of application entity titles to presentation addresses
        `presentationContextSelectionPolicy` - which SOP Classes and Transfer Syntaxes to accept and reject, or null for the default
        `secureTransport` - true if to use secure transport protocol
        `debugLevel` - zero for no debugging messages, higher values more verbose messages
      Throws:
        `java.io.IOException`

    - #### StorageSOPClassSCPDispatcher

          public StorageSOPClassSCPDispatcher​(int port,
                                              java.lang.String calledAETitle,
                                              java.io.File savedImagesFolder,
                                              StoredFilePathStrategy storedFilePathStrategy,
                                              ReceivedObjectHandler receivedObjectHandler,
                                              AssociationStatusHandler associationStatusHandler,
                                              QueryResponseGeneratorFactory queryResponseGeneratorFactory,
                                              RetrieveResponseGeneratorFactory retrieveResponseGeneratorFactory,
                                              NetworkApplicationInformation networkApplicationInformation,
                                              PresentationContextSelectionPolicy presentationContextSelectionPolicy,
                                              boolean secureTransport,
                                              int debugLevel)
                                       throws java.io.IOException

      Construct an instance of dispatcher that will wait for transport connection open indications, and handle associations and commands.

      Parameters:
        `port` - the port on which to listen for connections
        `calledAETitle` - our AE Title
        `savedImagesFolder` - the folder in which to store received data sets (may be null, to ignore received data for testing)
        `storedFilePathStrategy` - the strategy to use for naming received files and folders, or null for the default
        `receivedObjectHandler` - the handler to call after each data set has been received and stored, or null for the default that prints the file name
        `associationStatusHandler` - the handler to call when the Association is closed, or null if none required
        `queryResponseGeneratorFactory` - the factory to make handlers to generate query responses from a supplied query message
        `retrieveResponseGeneratorFactory` - the factory to make handlers to generate retrieve responses from a supplied retrieve message
        `networkApplicationInformation` - from which to obtain a map of application entity titles to presentation addresses
        `presentationContextSelectionPolicy` - which SOP Classes and Transfer Syntaxes to accept and reject, or null for the default
        `secureTransport` - true if to use secure transport protocol
        `debugLevel` - zero for no debugging messages, higher values more verbose messages
      Throws:
        `java.io.IOException`

  - ### Method Detail

    - #### isReady

          public boolean isReady()

      Is the dispatcher ready to receive connections?

      Useful for unit tests so as to know when to start sending to it.

      return true if ready

    - #### shutdown

          public void shutdown()

      Request the dispatcher to stop listening and exit the thread.

    - #### run

          public void run()

      Waits for a transport connection indications, then spawns new threads to act as association acceptors, which then wait for storage or verification commands, storing data sets in Part 10 files in the specified folder, until the associations are released or the transport connections are closed.

      Specified by:
        `run` in interface `java.lang.Runnable`

    - #### main

          public static void main​(java.lang.String[] arg)

      For testing.

      Wait for connections, accept associations and store received files in the specified folder.

      Parameters:
        `arg` - array of zero, four, five or eight strings - our port, our AE Title, optionally the max PDU size, socket receive and send buffer sizes, the folder in which to stored received files (zero length or "-" if want to ignore received data), optionally a string flag valued SECURE or other, and the debugging level; if no arguments are supplied the properties in "~/.com.pixelmed.network.StorageSOPClassSCPDispatcher.properties" will be used if present, otherwise the defaults (11112,STORESCP,~/tmp,debug level 0) will be used - in this mode the service will also be self-registered with dns-sd if possible