org.dvb.dsmcc
Class ServiceDomain

java.lang.Object
  extended by org.dvb.dsmcc.ServiceDomain

public class ServiceDomain
extends java.lang.Object

NOTE [GEM P.2.5]: The original first paragraph has been replaced with the following: A ServiceDomain represents the entity described in GEM clause B.1: "A service domain is an entity that uniquely identifies a filesystem, which can contain files, directories, stream descriptions, trigger objects and trigger events."

NOTE [GEM P.2.5]: Throughout this class, references to "service gateway" or "service domain" are to be interpreted as referring to service domain, as described in clause B.1.

To access the objects of a ServiceDomain, it has to be attached to the file system name space of the GEM 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 GEM 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 GEM 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()
          NOTE [GEM P.2.5.3]: The original description has been replaced with the following: 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)
          NOTE [GEM P.2.5.5]: The original description has been replaced with the following: Returns a URL corresponding to a locator referring to a file or a directory, as specified in the table in GEM clause 14.8, "Locators and content referencing." If the service domain corresponding to the locator is attached and the file or directory referenced in the locator exists then an instance of java.net.URL is returned which can be used to reference this object.
 boolean isAttached()
          Return whether this service domain is in the attached or detached state.
 boolean isNetworkConnectionAvailable()
          NOTE [GEM P.2.5.6]: The original description has been replaced with the following: This method shall return true if and only if the source(s) of data for this filesystem are connected and physically available to the terminal.
 
Methods inherited from class java.lang.Object
equals, 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.

NOTE [GEM P.2.5.2.2]: This method is not applicable in IPTV and shall always fail with a ServiceXFRException.

Parameters:
aDVBService - The coordinates of the DVB service which contains the object carousel. This locator has to point to a DVB service. NOTE [GEM P.2.5.2.2]: The locator parameter is to be interpreted as any locator that refers to a service.
aCarouselId - The identifier of the carousel. NOTE [GEM P.2.5.2.2]: The integer is to be interpreted as a unique identification of a service domain within the service.
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. NOTE [GEM P.2.5.2.1]: The locator parameter is to be interpreted as any locator that refers to a service domain.
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.

NOTE: [GEM P.2.5.1]: signalling to support an NSAP address is not required. In GEM Terminal Specifications where such signalling is not defined, it is a valid implementation for this method to do nothing.

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 GEM 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 GEM 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.

NOTE [GEM P.2.5.4]: Signalling to support this method is not required by GEM. In terminal specifications where no such signalling is defined, the behaviour of invoking this method may be undefined.

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
NOTE [GEM P.2.5.5]: The original description has been replaced with the following: Returns a URL corresponding to a locator referring to a file or a directory, as specified in the table in GEM clause 14.8, "Locators and content referencing." If the service domain corresponding to the locator is attached and the file or directory referenced in the locator exists then an instance of java.net.URL is returned which can be used to reference this object.

Parameters:
l - a locator referring to a file or directory, as specified in the table in GEM clause 14.8.
Returns:
a java.net.URL which can be used to access the file or directory referenced by the locator.
Throws:
InvalidLocatorException - if the locator is not a valid locator or does not includes all elements leading to a file or directory.
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 or directory 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()
NOTE [GEM P.2.5.6]: The original description has been replaced with the following: This method shall return true if and only if the source(s) of data for this filesystem are connected and physically available to the terminal.

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()
NOTE [GEM P.2.5.3]: The original description has been replaced with the following: 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. If the attach was done with the attach(locator, int) signature, the locator is complemented with a representation of the integer.

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