Requesting and Receiving Associations
Once you have registered one or more applications, you can initiate an association using one of the requestAssociation methods, or wait for an association using one of the startListening methods.
Releasing or Aborting the Association
The DICOM standard requires the association requester to release the association when no further processing is required. This is done using the release() method of the MCassociation class.
At any time either association partner may abort the association using the abort() method of the MCassociation class.
After calling release or abort, no other methods should be called for the association object. When the network partner releases or aborts the association, the application is notified by a specific status returned by the MCassociation.readMessage() method. See the Association Message Handling topic for an example of a typical message handling loop.
Preparing a Proposed Context List
Before you establish an association you must determine what DICOM services you are prepared to handle and perhaps create an MCproposedContextList object to manage the service information.
If you wish to propose the services that are configured in a [
You also have the option of creating your own proposed context list at run time. An MCproposedContextList object represents a collection of MCproposedContext objects, each representing:
Before you can create an MCproposedContext object you must create one or more
MCtransferSyntaxList objects representing the transfer syntaxes you want to use for the services. The MCtransferSyntaxList class represents a collection of
MCtransferSyntax objects.
Transfer Syntax Lists
Again, you have the option of creating an MCtransferSyntaxList object based on
configuration information, or you can create a new transfer syntax list at run time. To create an
MCtransferSyntaxList object from transfer syntaxes configured in a
[<syntax_list_name>] section of the Application Profile (mergecom.app) file, use the
MCtransferSyntaxList(String) constructor.
To create your own transfer syntax list you can use one of the other constructors of the MCtransferSyntaxList class and pass it an array of
MCtransferSyntax objects. The name of the transfer syntax lists identifies the list inside the toolkit and it must be unique among all transfer syntax lists (configured or dynamic).
MCtransferSyntax objects can be created only for transfer syntaxes known to the toolkit, i.e. those configured in the [ASSOC_PARMS] section of the System Profile (mergecom.pro) file.. You can either use the
MCtransferSyntax.getSyntax() static method to obtain the transfer syntax object for a particular UID or use one of the static fields of the MCtransferSyntax class to get the instance of the most frequently used syntaxes.
DICOM Services
The MCsopClass class provides a simple way to manage DICOM services. A service is identified either by its name or by its DICOM Unique Identifier (UID). Valid service names and UIDs are configured in the Service Profile (mergecom.srv) file.
For each service you want to include in your MCproposedContextList you must
specify what roles your application is prepared to play for the service. Your application may indicate whether the it is willing to perform the Service Class User(SCU) role and/or Service Class Provider(SCP) role. It may support either role or both roles. If these parameters are not specified the default role of the association requester is SCU only.
The MCproposedContext class provides methods to retrieve properties of the proposed context. The getSOPClass() method retrieves the SOP Class used to identify the DICOM service of the context. Other methods of this class can be used to determine the transfer syntaxes, the roles negotiated and any extended negotiation associated with the context.
The MCresultContext class contains the properties of a service that has been accepted by both sides of a DICOM association. Instances of this class are returned by the getAcceptableContexts() method of the MCassociation object after the association has been accepted by the acceptor.
Configuring Remote Nodes for SCU Applications
Typical Merge DICOM SCU applications use the mergecom.app configuration file to configure SCP applications that it communicates with.
Using this configuration file requires that remote applications be configured before the library is initialized. It may be desirable
to configure remote nodes at run-time. The following example illustrates how the
requestAssociation method of
the
Starting an Association Requester
If your application will be an association requester, the MCapplication class provides several options you can use to request an association with a network partner.
The requestAssociation method has three forms:
All forms of the requestAssociation method are blocking and return only after the association is successfully established, rejected or an error occurs.
Starting an Association Acceptor
If your application will be an association acceptor (a server), the MCapplication
class provides the startListening method to start up an association request listener in a separate thread. The startListening() method returns after the listener is successfully started.
You must supply an instance of a class that implements the
MCacceptor interface. The toolkit will call the processAssociation() method of that instance for every received association request in a separate thread. The toolkit maintains a pool of threads for handling subsequent associations.
Two forms of the startListening method allow you to specify the TCP/IP port to be listened on and the other two forms will use the port number specified by the TCPIP_LISTEN_PORT configuration parameter, or on port 104, if the TCPIP_LISTEN_PORT configuration parameter is missing from the
System Profile (mergecom.pro).
Note that a given Application Entity may only make this call one time for a given port, without first calling
stopListening (see below). The toolkit supports different Application Entities listening on the same port and it also supports the same Application Entity listening on multiple ports.
If your application wants to stop listening for association requests on a given port for a given Application Entity, it must call the
stopListening method of the application object. This simply
requests that the library no longer accept connection requests on the port that are directed to this Application Entity. A server program may call this when it is about to shut down, and then wait for any active association to finish.
Accepting or Rejecting an Association
Before DICOM messages can be exchanged across the association, the association acceptor must either accept or reject the association request from the association requestor.
When the Merge DICOM library calls the processAssociation() method of your MCacceptor implementation, it has already determined that both the local and remote applications wish to perform at least one common service. The getAcceptableContexts method of the association object passed to the processAssociation() method may be used to examine the services that are agreeable to both sides. Several other methods are available in MCassociation class to inquire about the proposed association. The setNegotiationInfo method can be used to set any extended negotiation information to be returned in the association response.
If your application agrees with the acceptable services, it calls the accept method to establish the association between the two applications. If it disagrees, it calls the reject method.
Negotiated Transfer Syntaxes
Merge DICOM Toolkit supports all currently approved standard and encapsulated DICOM transfer syntaxes. Encapsulated transfer syntaxes require
compression of the pixel data contained in the message. These messages can be sent and received by the toolkit, although the toolkit will not do the actual compression and decompression. Encoding of this pixel data is discussed below.
During association negotiation a client (SCU) application will propose a set of presentation contexts over which DICOM communication can take place. Each presentation context consists of an abstract syntax (DICOM service) and a set of transfer syntaxes that the client (SCU) understands. The server (SCP) will typically accept a presentation context if it supports the abstract syntax and one of the proposed transfer syntaxes.
The toolkit allows for the negotiation of more than one transfer syntax for a given DICOM service. This functionality is of most use for applications supporting encapsulated transfer syntaxes. This functionality may be disabled by use of the ACCEPT_MUTLPLE_PRES_CONTEXTS configuration value. In order to understand how it is implemented, a more in depth description of DICOM association negotiation is required.
The presentation contexts supported for client (SCU) applications using Merge DICOM toolkit are also defined through the Merge DICOM Application Profile. The following is a typical client�s (SCU) configuration:
[Acme_Store_SCP]
[Storage_Service_List]
In this case, the client (SCU) would propose the CT Image Storage service in a single presentation contexts. The transfer syntaxes for each service are the three standard (non-encapsulated) DICOM transfer syntaxes.
The following example is the configuration for a client (SCU) that supports more than one presentation context for a service:
[Acme_Store_SCP]
[Storage_Service_List]
[CT_Syntax_List_1]
[CT_Syntax_List_2]
Server (SCP) applications are configured differently than client (SCU) applications. An SCP should include all of the transfer syntaxes a service supports in a single transfer syntax list. If more than one transfer syntax list is used for a service, server (SCP) applications will only support the transfer syntaxes contained in the first transfer syntax list. The following is an example configuration for a server (SCP):
[[Storage_Service_List]
[CT_Syntax_List_SCP]
As discussed previously, for server (SCP) applications, the order in which transfer syntaxes are specified in a transfer syntax list dictates the priority Merge DICOM toolkit places on them during association negotiation. In this case, Merge DICOM toolkit would select JPEG_BASELINE if proposed, followed by EXPLICIT_LITTLE_ENDIAN, IMPLICIT_LITTLE_ENDIAN, and EXPLICIT_BIG_ENDIAN.
Association Information
The MCassociation class contains methods that can be used to retrieve properties of the association.
See the description of those methods for a description of each particular piece of information.
Once an association has been negotiated, the two cooperating applications, the Service Class Provider (SCP) and the Service Class User (SCU) exchange DICOM messages on the association network connection. These messages are encapsulated in MCdimseMessage objects. The MCassociation class provides methods for sending and receiving messages as in the following example:
MCapplication
class can be used with dynamic proposed context list:
// create an application object for the local application (SCU)
MCapplication localApp = MCapplication.getApplication( "MyApplicationAE" );
// set up the remote application object (SCP)
MCproposedContext context = new MCproposedContext( MCsopClass.getSopClass( "STANDARD_CT" ), MCtransferSyntax.EXPLICIT_LE );
MCproposedContextList pcl = new MCproposedContextList( new MCproposedContext[] { context } );
MCremoteApplication remoteApp = new MCremoteApplication( "SCU_AE", "scu_host", 104, pcl );
// establish the association between the SCU and SCP
MCassociation association = localApp.requestAssociation( remoteApp );
- The first form takes the AE Title of the remote application to associate with. The presentation address (host name and port) and the relevant negotiation information for the remote application must be configured in the Application Profile (mergecom.app) file.
- The second form takes an MCremoteApplication object that contains all information needed in the association process about the remote application. This form is used when the remote application information is not pre-configured in the Application Profile (mergecom.app) file.
- The third form takes an additional MCrequester instance that will be used by the toolkit to process the association communication in a separate thread.
During association negotiation a client (SCU) application will propose a set of presentation contexts over which DICOM communication can take place. Each presentation context consists of an abstract syntax (DICOM service) and a set of transfer syntaxes that the client (SCU) understands. The server (SCP) will typically accept a presentation context if it supports the abstract syntax and one of the proposed transfer syntaxes.
As previously discussed, the abstract and transfer syntaxes supported by a server (SCP) are defined through a service list contained in the Merge DICOM Application Profile. When support within a server (SCP) is limited to the three non-encapsulated DICOM transfer syntaxes, the toolkit will transparently handle the use of multiple presentation contexts for a DICOM service. However, when encapsulated DICOM transfer syntaxes are used, the server (SCP) must be able to determine the transfer syntax of messages it receives so that it can properly parse the pixel data contained in them. When a single presentation context is negotiated for a DICOM service, the
MCassociation.getAcceptableContext(java.lang.String)
method can be used to determine the transfer syntax for a service.
When more than one presentation context is negotiated for a service, the
MCassociation.getAcceptableContext(java.lang.String, com.merge.mcw.MCtransferSyntax)
method of the received request message must be used to retrieve this transfer syntax.
PORT_NUMBER = 104
HOST_NAME = acme_sun1
SERVICE_LIST = Storage_Service_List
SERVICES_SUPPORTED = 1 # Number of Services
SERVICE_1 = STANDARD_CT
PORT_NUMBER = 104
HOST_NAME = acme_sun1
SERVICE_LIST = Storage_Service_List
SERVICES_SUPPORTED = 2 # Number of Services
SERVICE_1 = STANDARD_CT
SYNTAX_LIST_1 = CT_Syntax_List_1
SERVICE_2 = STANDARD_CT
SYNTAX_LIST_2 = CT_Syntax_List_2
SYNTAXES_SUPPORTED = 1 # Number of Syntaxes
SYNTAX_1 = JPEG_BASELINE
SYNTAXES_SUPPORTED = 1 # Number of Syntaxes
SYNTAX_1 = IMPLICIT_LITTLE_ENDIAN
SERVICES_SUPPORTED = 1 # Number of Services
SERVICE_1 = STANDARD_CT
SYNTAX_LIST_1 = CT_Syntax_List_SCP
SYNTAXES_SUPPORTED = 4 # Number of Syntaxes
SYNTAX_1 = JPEG_BASELINE
SYNTAX_2 = EXPLICIT_LITTLE_ENDIAN
SYNTAX_3 = IMPLICIT_LITTLE_ENDIAN
SYNTAX_4 = EXPLICIT_BIG_ENDIAN
// Create a dimse message
MCdimseMessage msg = new MCdimseMessage();
// populate the message with attribute values
...
// send the request message
association.sendRequest( msg );
// read the response
MCreadStatus stat = association.readMessage( 60 );
// check the read result
if( !stat.succeeded() )
{
// communication error
System.out.println( "Failed to read response message: " + stat.getErrorMessage() );
association.abort();
return;
}
// check the response message for success
MCdimseMessage response = stat.message;
int responseStatus = response.getResponseStatus();
if( responseStatus != MCresponseStatus.SUCCESS )
{
// the SCP failed to store the instance
System.out.println( "The SCP failed to store the instance, 0x" + Integer.toHexString( responseStatus ) + " " + response.getErrorComment() );
}
else
{
// the operation succeeded
System.out.println( "Success" );
}