org.dvb.dsmcc
Class ServiceDomain

java.lang.Object
  extended byorg.dvb.dsmcc.ServiceDomain

public class ServiceDomain
extends java.lang.Object

A ServiceDomain represents a group of DSMCC objects. The objects are sent either using the object carousel for a broadcast network or with the DSM-CC User-to-User protocol for an interactive network.

To access the objects of a ServiceDomain, it has to be attached to the file system name space of the MHP terminal. To access the content of an object, the application has four ways:

Instances of ServiceDomain exist in two states, attached and detached. Newly created instances are always in the detached state. They become attached when a call to the attach method succeeds. They become detached following a call to the detach method.

When service domains in the attached state temporarily lose their network connection (e.g. if the MHP terminal tunes away from the transport stream where they are carried), the behaviour of DSMCC objects which are part of the service domain is specified in the main body of the present document. If such a network connection becomes available again then the service domain shall resume normal behaviour.

A service domain which is temporarily lost its network connection may be forced into the detached state by the implementation if the loss of the network connection becomes irrecoverable. The precise details of when this happens are implementation dependent. This is the only situation when shall be forced into the detached state. Once a ServiceDomain is detached, it will never be automatically attached.


Constructor Summary
ServiceDomain()
          Creates a ServiceDomain object.
 
Method Summary
 void attach(byte[] NSAPAddress)
          This function is used to attach a ServiceDomain from either an object carousel or from an interactive network.
 void attach(Locator l)
          This function is used to attach a ServiceDomain from an object carousel.
 void attach(Locator aDVBService, int aCarouselId)
          This function is used to attach a ServiceDomain from an object carousel.
 void detach()
          A call to this method is a hint that the applications gives to the MHP to unmount the volume and delete the objects of the service domain.
 byte[] getContextData(int context_id)
          Returns the context_data_bytes from the service context list of the ServiceDomain's service gateway object.
 Locator getLocator()
          Return the locator for this service domain.
 DSMCCObject getMountPoint()
          Returns a DSMCCObject object describing the top level directory of this ServiceDomain.
 byte[] getNSAPAddress()
          This method returns the NSAP address of the ServiceDomain.
static java.net.URL getURL(Locator l)
          Obtain a java.net.URL corresponding to a 'dvb:' locator.
 boolean isAttached()
          Return whether this service domain is in the attached or detached state.
 boolean isNetworkConnectionAvailable()
          Return whether the network connection for this service domain is available.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ServiceDomain

public ServiceDomain()
Creates a ServiceDomain object.

Method Detail

attach

public void attach(Locator aDVBService,
                   int aCarouselId)
            throws ServiceXFRException,
                   java.io.InterruptedIOException,
                   MPEGDeliveryException
This function is used to attach a ServiceDomain from an object carousel. It loads the module which contains the service gateway object and mounts the ServiceDomain volume in the file system hierarchy. This call will block until the service gateway is loaded. It can be aborted by another thread with the method detach. In this case an InterruptedIOException is thrown.

Calling this method on a ServiceDomain object already in the attached state shall imply a detach of the ServiceDomain object before the attach operation unless the ServiceDomain is already attached to the correct location. Hence if the attach operation fails, the appropriate exception for the failure mode shall be thrown and the ServiceDomain is left in a detached state and not attached to the former object carousel / service domain. If the ServiceDomain is already attached to the correct location then the method call shall have no effect.

Parameters:
aDVBService - The coordinates of the DVB service which contains the object carousel. This locator has to point to a DVB service.
aCarouselId - The identifier of the carousel.
Throws:
java.io.InterruptedIOException - The attachment has been aborted.
MPEGDeliveryException - An MPEG error occurred (such as time-out).
ServiceXFRException - The service gateway cannot be loaded in the current service domain. This exception shall not be thrown in this version of the specification.

attach

public void attach(Locator l)
            throws DSMCCException,
                   java.io.InterruptedIOException,
                   MPEGDeliveryException
This function is used to attach a ServiceDomain from an object carousel. It loads the module which contains the service gateway object and mounts the ServiceDomain volume in the file system hierarchy. This call will block until the service gateway is loaded. It can be aborted by another thread with the method detach. In this case an InterruptedIOException is thrown.

Calling this method on a ServiceDomain object already in the attached state shall imply a detach of the ServiceDomain object before the attach operation unless the ServiceDomain is already attached to the correct location. Hence if the attach operation fails, the appropriate exception for the failure mode shall be thrown and the ServiceDomain is left in a detached state and not attached to the former object carousel / service domain. If the ServiceDomain is already attached to the correct location then the method call shall have no effect.

Parameters:
l - The locator pointing to the elementary stream carrying the DSI of the object carousel, or to a DVB service that carries one and only one object carousel.
Throws:
DSMCCException - An error has occurred during the attachment. For example, the locator does not point to a component carrying a DSI of an Object Carousel or to a service containing a single carousel
java.io.InterruptedIOException - The attachment has been aborted.
MPEGDeliveryException - attaching to this domain would require tuning.

attach

public void attach(byte[] NSAPAddress)
            throws DSMCCException,
                   java.io.InterruptedIOException,
                   InvalidAddressException,
                   MPEGDeliveryException
This function is used to attach a ServiceDomain from either an object carousel or from an interactive network. This call will block until the attachment is done.

Calling this method on a ServiceDomain object already in the attached state shall imply a detach of the ServiceDomain object before the attach operation unless the ServiceDomain is already attached to the correct location. Hence if the attach operation fails, the appropriate exception for the failure mode shall be thrown and the ServiceDomain is left in a detached state and not attached to the former object carousel / service domain. If the ServiceDomain is already attached to the correct location then the method call shall have no effect.

Parameters:
NSAPAddress - The NSAP Address of a ServiceDomain as defined in in ISO/IEC 13818-6
Throws:
java.io.InterruptedIOException - The attachment has been aborted.
InvalidAddressException - The NSAP Address is invalid.
DSMCCException - An error has occurred during the attachment.
MPEGDeliveryException - attaching to this domain would require tuning.

detach

public void detach()
            throws NotLoadedException
A call to this method is a hint that the applications gives to the MHP to unmount the volume and delete the objects of the service domain. When another application is using objects of the same service domain the method has no effects. When there are no other application using objects of the service domain, a call to this method is a hint that the MHP can free all the resources allocated to this service domain.

After this, the ServiceDomain will be in a non-attached state and will behave as if it had just been constructed. Subsequent calls to detach shall throw NotLoadedException.

Throws:
NotLoadedException - is thrown if the ServiceDomain is not attached or if there is no call to attach in progress.

getNSAPAddress

public byte[] getNSAPAddress()
                      throws NotLoadedException
This method returns the NSAP address of the ServiceDomain.

Returns:
the NSAP address of the ServiceDomain.
Throws:
NotLoadedException - is thrown if the ServiceDomain is not attached.

getURL

public static java.net.URL getURL(Locator l)
                           throws NotLoadedException,
                                  InvalidLocatorException,
                                  java.io.FileNotFoundException
Obtain a java.net.URL corresponding to a 'dvb:' locator. If the service domain corresponding to the locator is attached and the file referenced in the locator exists then an instance of java.net.URL is returned which can be used to reference this file.

Parameters:
l - a locator object encapsulating a 'dvb:' locator which includes a 'dvb_abs_path' element.
Returns:
a java.net.URL which can be used to access the file referenced by the 'dvb:' locator
Throws:
InvalidLocatorException - if the locator is not a valid 'dvb:' locator or does not includes all elements including 'dvb_abs_path' element
NotLoadedException - is thrown if the locator is valid and includes enough information but it references a service domain which is not attached.
java.io.FileNotFoundException - if the service domain is attached but the file referenced by the locator does not exist

getMountPoint

public DSMCCObject getMountPoint()
Returns a DSMCCObject object describing the top level directory of this ServiceDomain. If the ServiceDomain object is not attached then null is returned.

Returns:
an instance of org.dvb.dsmcc.DSMCCObject if attached or null otherwise
Since:
MHP 1.0.1

isNetworkConnectionAvailable

public boolean isNetworkConnectionAvailable()
Return whether the network connection for this service domain is available. This return value is independent of whether the service domain is attached or not. If a service domain is distributed across multiple network connections (e.g. using the optional support for DSMCC over IIOP) then this will reflect the availability of the network connection carrying the object mounted to the mount point.

Returns:
true if the network connection for this service domain is available otherwise false
Since:
MHP 1.0.1

isAttached

public boolean isAttached()
Return whether this service domain is in the attached or detached state.

Returns:
true if this service domain is in the attached state, otherwise false
Since:
MHP 1.0.1

getLocator

public Locator getLocator()
Return the locator for this service domain. If this ServiceDomain instance was last attached by specifying a locator then an equivalent locator shall be returned except if the original locator contained extra information that is not necessary to identify the service domain in which case this extra information is removed. If the attach was done with the attach(locator, int) signature, the locator is complemented with the component_tag value that the platform has identified during attaching the ServiceDomain. If this ServiceDomain instance was last attached by specifying an NSAP address then the locator shall be generated from that address. If this ServiceDomain has never been attached then null shall be returned.

The syntax of the NSAP address is defined in section titled "LiteOptionsProfileBody" in annex B of the MHP specification. It contains the same fields as the locator syntax specified in the System integration aspects clause. The locator is constructed by taking the fields out of the NSAP address and encoding them in the locator syntax together with the component_tag value that the platform has identified during attaching the ServiceDomain.

Returns:
a locator for this service domain
Since:
MHP 1.0.1

getContextData

public byte[] getContextData(int context_id)
                      throws NotLoadedException
Returns the context_data_bytes from the service context list of the ServiceDomain's service gateway object.

Parameters:
context_id - the context_id whose context_data is to be returned
Returns:
an array containing the context_data_bytes or null if the context_id specified is not present in the service context list.
Throws:
NotLoadedException - if the service domain is not loaded