ServiceDomain

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.dvb.dsmcc
Class ServiceDomain

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

    public class ServiceDomain

extends 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:

- It can instantiate the class that is used to read the object (java.io.FileInputStream or java.io.RandomAccessFile for a File or DSMCCStream for a stream) from its pathname. The loading of the object is implicit but the application has no way to abort it. NB: Obviously, for the Object Carousel, the write mode of java.io.RandomAccessFile is not allowed.
- It can instantiate a DSMCCObject and carry out a Synchronous loading. The loading can be aborted by the abort method of the DSMCCObject class. When the object is loaded, the application will instantiate the class used to read the object.
- It can instantiate a DSMCCObject and carry out an Asynchronous loading. So several loading can be started in parallel from the same thread.
- It is also possible to create directly a java.io.File for a DSMCC object.

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.
`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 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
`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,
                       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:
    `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,
                       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
    `InterruptedIOException` - The attachment has been aborted.
    `MPEGDeliveryException` - attaching to this domain would require tuning.

### attach

    public void attach(byte[] NSAPAddress)
                throws DSMCCException,
                       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:
    `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 URL getURL(Locator l)
                      throws NotLoadedException,
                             InvalidLocatorException,
                             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.
    `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

Overview | Package | Class | Use | Tree | Deprecated | Index | Help

PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD