public class MCapplication
extends java.lang.Object
Each DICOM entity is identified by a 1-16 byte application entity title. Association negotiation, for example, uses an application's entity title to create a network connection between two participating applications.
Static methods and instances of this class can be used by multiple threads concurrently.
Modifier and Type | Method and Description |
---|---|
void |
dispose()
Disposes this application object.
|
java.lang.String |
getAETitle()
Gets the DICOM application entity title for this instance.
|
static MCapplication |
getApplication(java.lang.String aeTitle)
Retrieves the
MCapplication object associated with an application entity (AE) title. |
static boolean |
isValidAE(java.lang.String ae)
Determines if a string is a valid DICOM Application Entity Title.
|
void |
registerValueStorageProvider(MCvalueStorageProvider provider,
int tag)
Registers a value storage provider that provides the storage objects to be used by the application to store
large attribute values.
|
void |
registerValueStorageProvider(MCvalueStorageProvider provider,
MCtag tag)
Registers a value storage provider that provides the storage objects to be used by the application to store
large attribute values.
|
void |
releaseValueStorageProvider(int tag)
Releases a previously registered value storage provider.
|
void |
releaseValueStorageProvider(MCtag tag)
Releases a previously registered value storage provider.
|
MCassociation |
requestAssociation(MCremoteApplication remoteAE)
Requests a DICOM association between this application and the specified remote application.
|
MCassociation |
requestAssociation(MCremoteApplication remoteAE,
int connectTimeout)
Requests a DICOM association between this application and the specified remote application.
|
MCassociation |
requestAssociation(MCremoteApplication remoteAE,
MCrequester handler)
Requests a DICOM association between this application and the specified remote application.
|
MCassociation |
requestAssociation(MCremoteApplication remoteAE,
MCuserIdentity userIdentity,
boolean requestResponse,
byte[] primaryField,
byte[] secondaryField)
Requests a DICOM association between this application and the specified remote application with User Identity.
|
MCassociation |
requestAssociation(MCremoteApplication remoteAE,
MCuserIdentity userIdentity,
boolean requestResponse,
byte[] primaryField,
byte[] secondaryField,
int connectTimeout)
Requests a DICOM association between this application and the specified remote application with User Identity.
|
MCassociation |
requestAssociation(java.lang.String remoteAETitle)
Requests a DICOM association between this application and the specified remote application.
|
MCassociation |
requestAssociation(java.lang.String remoteAETitle,
MCuserIdentity userIdentity,
boolean requestResponse,
byte[] primaryField,
byte[] secondaryField)
Requests a DICOM association between this application and the specified remote application with User Identity.
|
void |
startListening(int port,
MCproposedContextList contextList,
MCacceptor handler)
Starts a listener for DICOM association requests directed to this application.
|
void |
startListening(int port,
java.lang.String serviceListName,
MCacceptor handler)
Starts a listener for DICOM association requests directed to this application.
|
int |
startListening(MCproposedContextList contextList,
MCacceptor handler)
Starts a listener for DICOM association requests directed to this application.
|
int |
startListening(java.lang.String serviceListName,
MCacceptor handler)
Starts a listener for DICOM association requests directed to this application.
|
void |
stopListening(int port)
Tells the toolkit to stop listening for DICOM associations on the specified port.
|
public static MCapplication getApplication(java.lang.String aeTitle)
MCapplication
object associated with an application entity (AE) title.
This factory method ensures that only one instance of MCapplication
class is active for any
given application entity (AE) title. The first call for a particular AE title value returns a new instance and
subsequent calls for the same AE title return the same instance unless the instance has been disposed, in which
case a new instance is returned.
aeTitle
- The Application Entity Title of the requested application. This value is subject to the
restrictions imposed by DICOM for an AE value representation type.MCapplication
instance for the requested AE title.MCexception
- If the AE title parameter is invalid.public static boolean isValidAE(java.lang.String ae)
ae
- The string to verify.true
if the string value validates according to the encoding rules defined by DICOM for
the AE value representation.public java.lang.String getAETitle()
public void dispose()
This method gives the library the opportunity to release any resource associated to this application.
Any attempt to use this application object after it is disposed will result in an exception being thrown.
To get a new application instance for the same AE Title use getApplication( String )
method.
public MCassociation requestAssociation(java.lang.String remoteAETitle)
This call is synchronous and returns only after the toolkit receives the association acceptance response from the remote application. If the association request is rejected by the remote application or a communication error occurs this method throws an exception.
The remote application's presentation address (host name and port number) and the list of services proposed in the association request must be specified in the mergecom.app configuration file for the given remote application entity title.
The toolkit will attempt to negotiate an association with the remote DICOM application. When the association request is received by the remote DICOM system, the remote application must be able to perform at least one of the services in the proposed service list (as configured in the mergecom.app for the remote application). If the association is accepted, information about the services that were acceptable to both sides can be retrieved from the returned association object.
remoteAETitle
- The application entity title of the remote DICOM application.MCassociation
instance for the connected association.MCexception
- If the argument is invalid, the connection failed, a communication error occurred or the
remote application rejected the association request. Check the value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public MCassociation requestAssociation(java.lang.String remoteAETitle, MCuserIdentity userIdentity, boolean requestResponse, byte[] primaryField, byte[] secondaryField)
This call is synchronous and returns only after the toolkit receives the association acceptance response from the remote application. If the association request is rejected by the remote application or a communication error occurs this method throws an exception.
The remote application's presentation address (host name and port number) and the list of services proposed in the association request must be specified in the mergecom.app configuration file for the given remote application entity title.
The toolkit will attempt to negotiate an association with the remote DICOM application. When the association request is received by the remote DICOM system, the remote application must be able to perform at least one of the services in the proposed service list (as configured in the mergecom.app for the remote application). If the association is accepted, information about the services that were acceptable to both sides can be retrieved from the returned association object.
remoteAETitle
- The application entity title of the remote DICOM application.userIdentity
- An MCuserIdentity
value.requestResponse
- True
if the positive response is requested.primaryField
- The primary field that conveys the user identity, either the username as a series of
characters, or the Kerberos Service ticket encoded in accordance with RFC-1510,
or the JWT encoded in accordance with RFC 7519 using base64url encoded parts.secondaryField
- The secondary field is present only if MCuserIdentity
value is
MCuserIdentity.USERNAME_AND_PASSCODE
and contains the passcode value.MCassociation
instance for the connected association.MCexception
- If the argument is invalid, the connection failed, a communication error occurred or the
remote application rejected the association request. Check the value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public MCassociation requestAssociation(MCremoteApplication remoteAE)
This call is synchronous and returns only after the toolkit receives the association acceptance response from the remote application. If the association request is rejected by the remote application or a communication error occurs this method throws an exception.
The toolkit will attempt to negotiate an association with the remote DICOM application. When the association request is received by the remote DICOM system, the remote application must be able to perform at least one of the services in the proposed service list of the remote application object passed as argument. If the association is accepted, information about the services that were acceptable to both sides can be retrieved from the returned association object.
remoteAE
- The remote application object containing information about the DICOM application to connect to.MCassociation
instance for the connected association.MCexception
- If the argument is invalid, the connection failed, a communication error occurred or the
remote application rejected the association request. Check the value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public MCassociation requestAssociation(MCremoteApplication remoteAE, int connectTimeout)
This call is synchronous and returns only after the toolkit receives the association acceptance response from the remote application. If the association request is rejected by the remote application or a communication error occurs this method throws an exception.
The toolkit will attempt to negotiate an association with the remote DICOM application. When the association request is received by the remote DICOM system, the remote application must be able to perform at least one of the services in the proposed service list of the remote application object passed as argument. If the association is accepted, information about the services that were acceptable to both sides can be retrieved from the returned association object.
remoteAE
- The remote application object containing information about the DICOM application to connect to.MCassociation
instance for the connected association.MCexception
- If the argument is invalid, the connection failed, a communication error occurred or the
remote application rejected the association request. Check the value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public MCassociation requestAssociation(MCremoteApplication remoteAE, MCuserIdentity userIdentity, boolean requestResponse, byte[] primaryField, byte[] secondaryField)
This call is synchronous and returns only after the toolkit receives the association acceptance response from the remote application. If the association request is rejected by the remote application or a communication error occurs this method throws an exception.
The toolkit will attempt to negotiate an association with the remote DICOM application. When the association request is received by the remote DICOM system, the remote application must be able to perform at least one of the services in the proposed service list of the remote application object passed as argument. If the association is accepted, information about the services that were acceptable to both sides can be retrieved from the returned association object.
remoteAE
- The remote application object containing information about the DICOM application to connect to.userIdentity
- An MCuserIdentity
value.requestResponse
- True
if the positive response is requested.primaryField
- The primary field that conveys the user identity, either the username as a series
of characters, or the Kerberos Service ticket encoded in accordance with RFC-1510,
or the JWT encoded in accordance with RFC 7519 using base64url encoded parts.secondaryField
- The secondary field is present only if MCuserIdentity
value is
MCuserIdentity.USERNAME_AND_PASSCODE
and contains the passcode value.MCassociation
instance for the connected association.MCexception
- If the argument is invalid, the connection failed, a communication error occurred or the
remote application rejected the association request. Check the value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public MCassociation requestAssociation(MCremoteApplication remoteAE, MCuserIdentity userIdentity, boolean requestResponse, byte[] primaryField, byte[] secondaryField, int connectTimeout)
This call is synchronous and returns only after the toolkit receives the association acceptance response from the remote application. If the association request is rejected by the remote application or a communication error occurs this method throws an exception.
The toolkit will attempt to negotiate an association with the remote DICOM application. When the association request is received by the remote DICOM system, the remote application must be able to perform at least one of the services in the proposed service list of the remote application object passed as argument. If the association is accepted, information about the services that were acceptable to both sides can be retrieved from the returned association object.
remoteAE
- The remote application object containing information about the DICOM application to connect to.userIdentity
- An MCuserIdentity
value.requestResponse
- True
if the positive response is requested.primaryField
- The primary field that conveys the user identity, either the username as a series
of characters, or the Kerberos Service ticket encoded in accordance with RFC-1510,
or the JWT encoded in accordance with RFC 7519 using base64url encoded parts.secondaryField
- The secondary field is present only if MCuserIdentity
value is
MCuserIdentity.USERNAME_AND_PASSCODE
and contains the passcode value.connectTimeout
- Connect timeout for this association request only (supersedes the global CONNECT_TIMEOUT
configuration setting)MCassociation
instance for the connected association.MCexception
- If the argument is invalid, the connection failed, a communication error occurred or the
remote application rejected the association request. Check the value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public MCassociation requestAssociation(MCremoteApplication remoteAE, MCrequester handler)
This call is synchronous and returns only after the toolkit receives the association acceptance response from the remote application. If the association request is rejected by the remote application or a communication error occurs this method throws an exception.
The toolkit will use an internal thread to call the handler's processAssociation method once the association is established. There is no guarantee whether this method returns before or after the handler's processAssociation method is called.
The toolkit will attempt to negotiate an association with the remote DICOM application. When the association request is received by the remote DICOM system, the remote application must be able to perform at least one of the services in the proposed service list of the remote application object passed as argument. If the association is accepted, information about the services that were acceptable to both sides can be retrieved from the returned association object.
remoteAE
- The remote application object containing information about the DICOM application to connect to.handler
- An MCrequester
instance that will handle the communication for the established
association.MCassociation
instance for the connected association.MCexception
- If an argument is invalid, the connection failed, a communication error occurred or the
remote application rejected the association request. Check the value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public int startListening(java.lang.String serviceListName, MCacceptor handler)
This method can be used to start a socket listener so that this application is able to receive association requests from other applications. This method is asynchronous and returns after the socket listener is successfully started, it does not block until an association request arrives.
The port number to listen on is configured through the TCPIP_LISTEN_PORT configuration option.
On platforms that support IPv6, the IP_TYPE configuration option can be used to tell the toolkit whether to listen for IPv4 or IPv6 connections.
Different applications can listen on the same port. Also the same application can listen on multiple ports.
Whenever an association request is received for this application and at least one of the proposed services is
acceptable, the toolkit calls the processAssociation method of the handler, passing the MCassociation
object that represents the association being negotiated. It is the handler's responsibility to call either the
MCassociation.accept()
or MCassociation.reject()
methods on the association object to accept or
reject the request.
Each association request is handled in a separate thread, meaning the MCacceptor.processAssociation(com.merge.mcw.MCassociation)
method of
the handler is called by the toolkit in a thread reserved for that association. The lifetime of the association
is not tied to the duration of the MCacceptor.processAssociation(com.merge.mcw.MCassociation)
call. After the start()
call
returns the toolkit may reuse the thread for a future association.
To stop receiving association requests use the stopListening(int)
method.
serviceListName
- The name of a service list containing services supported by this application. The
service list must be configured in mergecom.app or create dynamically using MCproposedContextList
class.handler
- An MCacceptor
instance that will handle the received associations.MCexception
- If an argument is invalid or the toolkit failed to set up the listener socket. Check the
value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public int startListening(MCproposedContextList contextList, MCacceptor handler)
This method can be used to start a socket listener so that this application is able to receive association requests from other applications. This method is asynchronous and returns after the socket listener is successfully started, it does not block until an association request arrives.
The port number to listen on is configured through the TCPIP_LISTEN_PORT configuration option.
On platforms that support IPv6, the IP_TYPE configuration option can be used to tell the toolkit whether to listen for IPv4 or IPv6 connections.
Different applications can listen on the same port. Also the same application can listen on multiple ports.
Whenever an association request is received for this application and at least one of the proposed services is
acceptable, the toolkit calls the processAssociation method of the handler, passing the MCassociation
object that represents the association being negotiated. It is the handler's responsibility to call either the
MCassociation.accept()
or MCassociation.reject()
methods on the association object to accept or
reject the request.
Each association request is handled in a separate thread, meaning the MCacceptor.processAssociation(com.merge.mcw.MCassociation)
method of the handler is called by the toolkit in a thread reserved for that association. The lifetime of
the association is not tied to the duration of the MCacceptor.processAssociation(com.merge.mcw.MCassociation)
call. After the
MCacceptor.processAssociation(com.merge.mcw.MCassociation)
call returns the toolkit may reuse the thread for a future association.
To stop receiving association requests use the stopListening(int)
method.
contextList
- The service list containing services supported by this application.handler
- An MCacceptor
instance that will handle the received associations.MCexception
- If an argument is invalid or the toolkit failed to set up the listener socket. Check the
value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public void startListening(int port, java.lang.String serviceListName, MCacceptor handler)
This method can be used to start a socket listener so that this application is able to receive association requests from other applications. This method is asynchronous and returns after the socket listener is successfully started, it does not block until an association request arrives.
On platforms that support IPv6, the IP_TYPE configuration option can be used to tell the toolkit whether to listen for IPv4 or IPv6 connections.
Different applications can listen on the same port. Also the same application can listen on multiple ports.
Whenever an association request is received for this application and at least one of the proposed services is
acceptable, the toolkit calls the processAssociation method of the handler, passing the MCassociation
object that represents the association being negotiated. It is the handler's responsibility to call either the
MCassociation.accept()
or MCassociation.reject()
methods on the association object to accept or
reject the request.
Each association request is handled in a separate thread, meaning the MCacceptor.processAssociation(com.merge.mcw.MCassociation)
method of the handler is called by the toolkit in a thread reserved for that association. The lifetime of
the association is not tied to the duration of the MCacceptor.processAssociation(com.merge.mcw.MCassociation)
call. After the
MCacceptor.processAssociation(com.merge.mcw.MCassociation)
call returns the toolkit may reuse the thread for a future association.
To stop receiving association requests use the stopListening(int)
method.
port
- The port number to listen on.serviceListName
- The name of a service list containing services supported by this application. The
service list must be configured in mergecom.app or create dynamically using MCproposedContextList
class.handler
- An MCacceptor
instance that will handle the received associations.MCexception
- If an argument is invalid or the toolkit failed to set up the listener socket. Check the
value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public void startListening(int port, MCproposedContextList contextList, MCacceptor handler)
This method can be used to start a socket listener so that this application is able to receive association requests from other applications. This method is asynchronous and returns after the socket listener is successfully started, it does not block until an association request arrives.
On platforms that support IPv6, the IP_TYPE configuration option can be used to tell the toolkit whether to listen for IPv4 or IPv6 connections.
Different applications can listen on the same port. Also the same application can listen on multiple ports.
Whenever an association request is received for this application and at least one of the proposed services is
acceptable, the toolkit calls the processAssociation method of the handler, passing the MCassociation
object that represents the association being negotiated. It is the handler's responsibility to call either the
MCassociation.accept()
or MCassociation.reject()
methods on the association object to accept or
reject the request.
Each association request is handled in a separate thread, meaning the MCacceptor.processAssociation(com.merge.mcw.MCassociation)
method of the handler is called by the toolkit in a thread reserved for that association. The lifetime of the
association is not tied to the duration of the MCacceptor.processAssociation(com.merge.mcw.MCassociation)
call. After the
MCacceptor.processAssociation(com.merge.mcw.MCassociation)
call returns the toolkit may reuse the thread for a future association.
To stop receiving association requests use the stopListening(int)
method.
port
- The port number to listen on.contextList
- The service list containing services supported by this application..handler
- An MCacceptor
instance that will handle the received associations.MCexception
- If an argument is invalid or the toolkit failed to set up the listener socket. Check the
value of the MCexception.exceptionNumber
field of the exception object for the cause of the failure.public void stopListening(int port)
Any associations that is currently active will not be affected.
If there are other MCapplication
objects listening on the same port the toolkit will continue to
receive associations for them. This method affects only associations received for this application.
port
- The port number to stop listening on. If zero (0) the toolkit will stop listening on all ports for
this application.public void registerValueStorageProvider(MCvalueStorageProvider provider, int tag)
Methods of the obtained MCvalueStorage
instances will be called by the toolkit to provide or
retrieve an attribute's values as it is transmitted or received on a DICOM association or read or written
to a DICOM file.
This method may only be called for attributes with Value Representations of OB, OW, OV, OL, OD or OF.
When receiving data from the network or reading data from a file and a provider is registered for a certain
attribute the toolkit will call the provider's getStorage
method to
obtain an object that will be responsible for storing the attributes value. The toolkit will not store the
attribute's value internally and will call the methods of the storage object whenever it needs it. The
CALLBACK_MIN_DATA_SIZE configuration option can be used to control the minimum size of an attribute for
which the toolkit uses application provided storage. Note however that the CALLBACK_MIN_DATA_SIZE does not
apply to encapsulated values with undefined length.
When sending data over the network or writing DICOM files, the toolkit uses application provided storage only
if the attribute does not have a value set through one of the setValue
or addValue
methods of MCattributeSet
. In that case the attribute may either have a value stored in a
MCvalueStorage
instance (as the result of a read operation) or it does not have a value at all
( added to the attribute set using the MCattributeSet.addAttribute(com.merge.mcw.MCtag)
method).
Any previously registered value storage provider for the same tag is released.
provider
- The MCvalueStorageProvider
instance that provides storage for the specified attribute.tag
- The tag number for which to register the provider.public void registerValueStorageProvider(MCvalueStorageProvider provider, MCtag tag)
Methods of the obtained MCvalueStorage
instances will be called by the toolkit to provide or
retrieve an attribute's values as it is transmitted or received on a DICOM association or read or written
to a DICOM file.
This method may only be called for attributes with Value Representations of OB, OW, OV, OL, OD or OF.
When receiving data from the network or reading data from a file and a provider is registered for a certain
attribute the toolkit will call the provider's getStorage
method to
obtain an object that will be responsible for storing the attributes value. The toolkit will not store the
attribute's value internally and will call the methods of the storage object whenever it needs it. The
CALLBACK_MIN_DATA_SIZE configuration option can be used to control the minimum size of an attribute for
which the toolkit uses application provided storage. Note however that the CALLBACK_MIN_DATA_SIZE does not
apply to encapsulated values with undefined length.
When sending data over the network or writing DICOM files, the toolkit uses application provided storage only
if the attribute does not have a value set through one of the setValue
or addValue
methods of MCattributeSet
. In that case the attribute may either have a value stored in a
MCvalueStorage
instance (as the result of a read operation) or it does not have a value at all
( added to the attribute set using the MCattributeSet.addAttribute(com.merge.mcw.MCtag)
method).
Any previously registered value storage provider for the same tag is released.
Note:
The method works correctly for standard attributes and for
private attribute whose private creator code is an ASCII string as MCapplication
does
not have a specific character set context to be able to encode Unicode strings.
provider
- The MCvalueStorageProvider
instance that provides storage for the specified attribute.tag
- The tag for which to register the provider.MCexception
- if the tag argument is nullpublic void releaseValueStorageProvider(int tag)
This method releases the value storage provider that was registered for the attribute identified by
tag
. The provider's method will no longer be called when the attribute's value is being received
or when the attribute's value is required. The value storage objects obtained before this call that are still
storing values in active attribute sets, will still be used.
tag
- The tag number for which the container was registered.public void releaseValueStorageProvider(MCtag tag)
tag
. The provider's method will no longer be called when the attribute's value is being received
or when the attribute's value is required. The value storage objects obtained before this call that are still
storing values in active attribute sets, will still be used.
Note:
The method works correctly for standard attributes and for
private attribute whose private creator code is an ASCII string as MCapplication
does
not have a specific character set context to be able to encode Unicode strings.
tag
- The tag for which the container was registered.