JSR-043: JTAPI-1.4

javax.telephony.media.container
Interface ContainerService

All Superinterfaces:
CoderConstants, ContainerConstants
All Known Subinterfaces:
Async_ContainerService
All Known Implementing Classes:
Base_ContainerService

public interface ContainerService
extends ContainerConstants

Methods for manipulating Containers. Containers correspond to filesystem directories. A Container may contain other Containers, Media Data Objects (MDOs), file objects, or other data objects.

MDO data objects in a Container are used for playing and recording with the Player.play() and Recorder.record() methods. File data objects are used to hold contexts and grammars for the the ASR interface.

Containers are manipulated by reference to their full name, which is a String in the usual heirarchical format as commonly seen in file pathnames or URLs. That is, strings of the form:
//servername/container1/.../containerN/dataobject

The separator characters between containers can be either of "/" or "\" (forward slash or back slash), and those characters can only be used as separators.

Note: the "//servername/" prefix can be omitted; the MediaProvider uses the servername of the host to which the MediaProvider is connected.

Note: in the future this format may be extended to include additional "protocol" names in the URL format. Developers should use the ":" character in names with caution.

A ContainerService object is obtained using:
((ContainerProvider)MediaProvider).getContainerService()

Since:
JTAPI-1.4

Fields inherited from interface javax.telephony.media.container.ContainerConstants
b_Append, b_Create, b_Exclusive, b_Truncate, e_OK, k_InputParameters, k_MediaType, k_MediaTypes, v_AccessCopy, v_AccessRead, v_AccessWrite, v_Begin, v_Bytes, v_Create, v_Current, v_End, v_Fail, v_MDO, v_MilliSeconds
 
Fields inherited from interface javax.telephony.media.CoderConstants
v_24kADPCM, v_32kADPCM, v_44kADPCM, v_48k8BitLinear, v_48kALawPCM, v_48kMuLawPCM, v_64k8BitLinear, v_64kALawPCM, v_64kMuLawPCM, v_88k8BitLinear, v_88kALawPCM, v_88kMuLawPCM, v_ADPCM_24k, v_ADPCM_32k, v_ADPCM_44k, v_ADSI, v_ALawPCM_48k, v_ALawPCM_64k, v_ALawPCM_88k, v_ASCII, v_Linear8Bit_48k, v_Linear8Bit_64k, v_Linear8Bit_88k, v_MuLawPCM_48k, v_MuLawPCM_64k, v_MuLawPCM_88k, v_TDD
 
Method Summary
 void changeMode(java.lang.String fullName, Symbol accessMode, java.util.Dictionary optargs)
          Change the static access rights of the named DataObject.
 void copy(java.lang.String fullName, java.lang.String target, java.util.Dictionary optargs)
          Copy a DataObject to a new DataObject name.
 void createContainer(java.lang.String fullName, java.util.Dictionary optargs)
          Create a new Container.
 DataObject createDataObject(java.lang.String fullName, Symbol accessMode, java.util.Dictionary optargs)
          Create a new Media Data Object and open it.
 void destroy(java.lang.String fullName, java.util.Dictionary optargs)
          Remove the named Container or DataObject.
 java.util.Dictionary getInfo(java.lang.String fullName, Symbol[] keys, java.util.Dictionary optargs)
          Return arbitrary user infomation stored with a Container or DataObject.
 java.util.Dictionary getParameters(java.lang.String fullName, Symbol[] keys, java.util.Dictionary optargs)
          Get system parameters on a Container or DataObject.
 java.lang.String[] listObjects(java.lang.String fullName, java.util.Dictionary optargs)
          List Containers and DataObjects contained in the named Container.
 DataObject openDataObject(java.lang.String fullName, Symbol accessMode, boolean ifNoExist, boolean truncate, java.util.Dictionary optargs)
          Open a Media Data Object.
 void rename(java.lang.String fullName, java.lang.String newName, java.util.Dictionary optargs)
          Rename a Container or DataObject within its current Container.
 void setInfo(java.lang.String fullName, java.util.Dictionary dict)
          Store arbitrary user infomation with a Container or DataObject.
 void setParameters(java.lang.String fullName, java.util.Dictionary params)
          Set system parameters on a Container or DataObject.
 

Method Detail

setInfo

public void setInfo(java.lang.String fullName,
                    java.util.Dictionary dict)
             throws ContainerException
Store arbitrary user infomation with a Container or DataObject.
Parameters:
fullName - the full Container or DataObject path String.
dict - a Dictionary of infomation to be stored on the container.
Throws:
ContainerException - if anything goes wrong.
See Also:
getInfo(java.lang.String, javax.telephony.media.Symbol[], java.util.Dictionary)

getInfo

public java.util.Dictionary getInfo(java.lang.String fullName,
                                    Symbol[] keys,
                                    java.util.Dictionary optargs)
                             throws ContainerException
Return arbitrary user infomation stored with a Container or DataObject.
Parameters:
fullName - the full Container or DataObject path String.
keys - a Symbol[] selecting the items to retrieve.
If keys is null, then retrieve all parameters.
optargs - a Dictionary of implementation-specific information.
Returns:
a Dictionary of information from the Container or DataObject.
Throws:
ContainerException - if anything goes wrong.
See Also:
setInfo(java.lang.String, java.util.Dictionary)

setParameters

public void setParameters(java.lang.String fullName,
                          java.util.Dictionary params)
                   throws ContainerException
Set system parameters on a Container or DataObject.
Parameters:
fullName - the full Container or DataObject path String.
params - a Dictionary of parameters to be set.
Throws:
ContainerException - if anything goes wrong.
See Also:
getParameters(java.lang.String, javax.telephony.media.Symbol[], java.util.Dictionary)

getParameters

public java.util.Dictionary getParameters(java.lang.String fullName,
                                          Symbol[] keys,
                                          java.util.Dictionary optargs)
                                   throws ContainerException
Get system parameters on a Container or DataObject.
Parameters:
fullName - the full Container or DataObject path String.
keys - a Symbol[] selecting the items to retrieve.
If keys is null, then retrieve all parameters.
optargs - a Dictionary of implementation-specific information.
Returns:
a Dictionary of information from the Container or DataObject.
Throws:
ContainerException - if anything goes wrong.
See Also:
setParameters(java.lang.String, java.util.Dictionary)

changeMode

public void changeMode(java.lang.String fullName,
                       Symbol accessMode,
                       java.util.Dictionary optargs)
                throws ContainerException
Change the static access rights of the named DataObject. The static mode of the DataObject restricts the mode available when the DataObject is opened for Read or Write. v_AccessRead means the object can be opened for read-only. v_AccessWrite means the object can be opend for read, write, or copy.
Parameters:
fullName - the name of the DataObject.
accessMode - one of the Symbols v_AccessRead, v_AccessWrite
optargs - a Dictionary of implementation-specific information.
Throws:
ContainerException - if anything goes wrong.

copy

public void copy(java.lang.String fullName,
                 java.lang.String target,
                 java.util.Dictionary optargs)
          throws ContainerException
Copy a DataObject to a new DataObject name. The new DataObject may be in the same or a different Container. The new Container must be on the same server.

This operation can fail for numerous reasons, including:

Parameters:
fullName - the current name of the Container
target - the new name for the Container
optargs - a Dictionary of implementation-specific information.
Throws:
ContainerException - if anything goes wrong.

rename

public void rename(java.lang.String fullName,
                   java.lang.String newName,
                   java.util.Dictionary optargs)
            throws ContainerException
Rename a Container or DataObject within its current Container.

Note: the newName is not a full path; it is just the last component of the new name, without any path separator characters.

Parameters:
fullName - the current name of Container/DataObject.
newName - the new name for the Container/DataObject.
optargs - a Dictionary of implementation-specific information.
Throws:
ContainerException - if fullName does not exist, or if newName already exists.

destroy

public void destroy(java.lang.String fullName,
                    java.util.Dictionary optargs)
             throws ContainerException
Remove the named Container or DataObject. If a Container is named, remove the Container and all DataObjects in that Container.

Note: Destroy can succeed even if the Container is in read-only mode.

Parameters:
fullName - the full Container or DataObject path String.
optargs - a Dictionary of implementation-specific information.
Throws:
ContainerException - if container does not exist.

listObjects

public java.lang.String[] listObjects(java.lang.String fullName,
                                      java.util.Dictionary optargs)
                               throws ContainerException
List Containers and DataObjects contained in the named Container.

The order of objects in the list is not specified.

Parameters:
fullName - the full Container path String.
optargs - a Dictionary of implementation-specific information.
Returns:
a String[] with an element for each object in the container.
Throws:
ContainerException - if container does not exist.

createContainer

public void createContainer(java.lang.String fullName,
                            java.util.Dictionary optargs)
                     throws ContainerException
Create a new Container.

Note:to create a new Data Object, use openObject().

Parameters:
fullName - the name of the new Container.
optargs - a Dictionary of implementation-specific information.
Throws:
ContainerException - container cannot be created.

createDataObject

public DataObject createDataObject(java.lang.String fullName,
                                   Symbol accessMode,
                                   java.util.Dictionary optargs)
                            throws ContainerException
Create a new Media Data Object and open it. Returns a DataObject that can be read or written.
Parameters:
fullName - the name of the DataObject to create.
accessMode - one of the Symbols v_AccessRead, v_AccessWrite, v_AccessCopy
optargs - a Dictionary of implementation-specific information.
Returns:
an open DataObject.
Throws:
ContainerException - if the Data Object is not opened.

openDataObject

public DataObject openDataObject(java.lang.String fullName,
                                 Symbol accessMode,
                                 boolean ifNoExist,
                                 boolean truncate,
                                 java.util.Dictionary optargs)
                          throws ContainerException
Open a Media Data Object. Returns a DataObject that can be read or written.

Note: unlike java.io streams, a DataObject is not differentiated between InputStream and OutputStream.

Argument accessMode one of the Symbols:
Symbol:Description:
v_AccessRead Sets non-exclusive READ access
v_AccessWrite Sets exclusive WRITE access
v_AccessCopy Sets WRITE access to the object while other READ accesses are being made. This access mode causes a new copy of the Object payload to be created. When the handle is closed, the new data will replace the old data such that any OPENs with READ access that occurred before this close will continue to see the old data, and any OPENs with READ access occurring after the close will see the new data.

If the named Data Object does not exist, the result is determined by the value of argument ifNoExist:

If argument accessMode is v_AccessWrite or v_AccessCopy, then argument truncate can be used to erase the contents of MDO when it is opened.

Parameters:
fullName - the name of the DataObject to open.
accessMode - one of the Symbols v_AccessRead, v_AccessWrite, v_AccessCopy
ifNoExist - one of v_Fail (false) or v_Create (true)
truncate - if true and v_AccessWrite or v_AccessCopy then immediately erase previous contents.
optargs - a Dictionary of implementation-specific information.
Returns:
an open DataObject.
Throws:
ContainerException - if the Data Object is not opened.

JSR-043: JTAPI-1.4

Send comments to: JSR-43@ectf.org