Main Page | Modules | Namespace List | Class Hierarchy | Alphabetical List | Compound List | File List | Namespace Members | Compound Members | File Members

sedris::seWorkspace Class Reference

#include <seWorkspace.h>

List of all members.

Public Member Functions

 seWorkspace (const char *name=NULL, const char *params=NULL)
virtual ~seWorkspace ()
virtual void open (const char *name=NULL, const char *params=NULL)
virtual void close ()
virtual bool isValid () const
virtual void setName (const char *name)
virtual const char * getName () const
 Returns the workspace name.

virtual void openTransmittalByFile (const char *file_name, seTransmittal &xmtal, SE_Access_Mode access_mode=SE_AC_MODE_READ_ONLY)
void createTransmittal (const char *file_name, seTransmittal &xmtal)
void editTransmittal (const char *file_name, seTransmittal &xmtal)
virtual void openTransmittalByURN (const char *xmtal_urn, seTransmittal &xmtal, SE_Access_Mode access_mode=SE_AC_MODE_READ_ONLY)
virtual unsigned int getOpenedTransmittalCount () const
virtual void getOpenedTransmittal (unsigned int index, seTransmittal &xmtal) const
virtual const char * resolveTransmittalURN (const char *xmtal_urn)
virtual void createUnresolvedObject (const char *xmtal_urn, const char *obj_label, seObject &obj) const
virtual void setITRBehaviour (SE_ITR_Behaviour itr_behaviour)
virtual SE_ITR_Behaviour getITRBehaviour ()
virtual void setAccessModeInheritance (bool tf)
virtual bool getAccessModeInheritance () const
virtual void setITRResolverPath (const char *new_path)
virtual const char * getITRResolverPath () const
virtual void setMemoryModel (unsigned int mem_model)
virtual unsigned int getMemoryModel () const
virtual const char * getImplVerInfo () const

Protected Member Functions

 seWorkspace (const seWorkspace &other)
 Not allowed.

seWorkspace & operator= (const seWorkspace &)
 Not allowed.

Detailed Description

The seWorkspace class groups access to transmittals under a common "theme". You can, for example, specify the ITR behaviour, resolver path, etc. to use when opening transmittals so that all transmittals under that workspace are opened and accessed using the same parameters. Example usage: 
    seWorkspace wksp;
    seTransmittal xmtal1, xmtal2;

    wksp.setITRResolverPath(myResolverPath);

    wksp.openTransmittalByFile(fileName1, xmtal1);
    wksp.openTransmittalByFile(fileName2, xmtal2);
    ... work on transmittals
Warning:
You can change the parameters of a workspace at any time, but be aware that transmittals don't "remember" the settings they were opened with, and that ALL the transmittals in that workspace will be using the new parameters from the moment the settings were changed.
Exceptions:
seException on error.
Author:
Warren Macchi (Accent Geographic)
See also:
seTransmittal

Constructor & Destructor Documentation

sedris::seWorkspace::seWorkspace (  const char *  name = NULL,
const char *  params = NULL
) 
 

Creates and opens an seWorkspace. Workspaces are the only way to open transmittals. You can keep as many workspaces as you need to group the opening/creation/access to transmittals. You can close() and re open() a workspace with the caveates explained in those methods.

Note:
There is no need to call open() unless you close the workspace.
See also:
setName()
Parameters:
name in: the name to use for this workspace
params in (optional): parameters to use in the workspace creation (experimental)

virtual sedris::seWorkspace::~seWorkspace (   )  [virtual]
 

Destructor, calls close().

See also:
close()

sedris::seWorkspace::seWorkspace (  const seWorkspace &  other  )  [inline, protected]
 

Member Function Documentation

virtual void sedris::seWorkspace::close (   )  [virtual]
 

Closes the workspace and releases the handle to the workspace. All transmittals opened by this workspace are closed. Note that after a workspace handle is close you can't do much with this handle. To make the workspace handle valid again you must call open() to open a new workspace.

Note:
seTransmittal and seObject handles remain valid, but you won't be able to do much with them except to release them.
Warning:
Closing a workspace forces the close of all opened transmittals in that workspace.
See also:
seTransmittal::close()

void sedris::seWorkspace::createTransmittal (  const char *  file_name,
seTransmittal &  xmtal
)  [inline]
 

Create a transmittal. Convenience method for openTransmittalByFile() in CREATE mode.

Warning:
If the transmittal file is already there, this method will OVERWRITE that transmittal.
See also:
openTransmittalByFile()
Parameters:
file_name in: file name and path of transmittal to create
xmtal in/out: the recipient transmittal handle

virtual void sedris::seWorkspace::createUnresolvedObject (  const char *  xmtal_urn,
const char *  obj_label,
seObject &  obj
)  const [virtual]
 

Creates an unresolved object that references an object in another transmittal. This method is used to create an object that references an object in another transmittal using the ITR mechanism. You can use the returned object pretty much like you would use any other object (for example you can add it as a component/associate of another). However, you cannot call methods that require it to be resolved since they will fail with an exception.

For example, to create an ITR reference to transmittal B and to add a published object B in that transmittal as a component of object A in transmittal A, you can do: 

            ...
            seObject itr_obj;

            wksp.createUnresolvedObject(urn_B, label_B, itr_obj);
            obj_A.addComponent(itr_obj);
If you need to add the reverse (aggregate) relationship in the B transmittal, you could do (assuming that object A was published with label A): 
            ...
            seObject itr_obj;

            wksp.createUnresolvedObject(urn_A, label_A, itr_obj);
            itr_obj.addComponent(obj_B);
Warning:
This function does not validate the reference to insure that it can be resolved. This behavior is intentional in order to allow referencing "well known" published objects, without requiring the transmittal containing the object to be accessible. Care must be taken to insure the reference is indeed correct.
Note:
The transmittal URN must pass SE_ValidTransmittalName() and the object label must pass SE_ValidObjectLabel(), or an exception will occur.
Parameters:
xmtal_urn in: the URN of the transmittal to reference
obj_label in: the label of the published object in the referenced transmittal.
obj in/out: a handle to store the created object

void sedris::seWorkspace::editTransmittal (  const char *  file_name,
seTransmittal &  xmtal
)  [inline]
 

Open a transmittal for edit. Convenience method for openTransmittalByFile() in UPDATE mode.

Exceptions:
seException if the transmittal file does not exist.
See also:
openTransmittalByFile()
Parameters:
file_name in: file name and path of transmittal to edit
xmtal in/out: the recipient transmittal handle
Returns:
true if successful

virtual bool sedris::seWorkspace::getAccessModeInheritance (   )  const [virtual]
 

Returns the workspace access mode inheritance flag.

See also:
setAccessModeInheritance()

virtual const char* sedris::seWorkspace::getImplVerInfo (   )  const [virtual]
 

Returns the implementation version of the API component.

virtual SE_ITR_Behaviour sedris::seWorkspace::getITRBehaviour (   )  [virtual]
 

Returns the workspace ITR behaviour. @see setITRBehaviour()

virtual const char* sedris::seWorkspace::getITRResolverPath (   )  const [virtual]
 

Returns the workspace resolver path.

See also:
getITRResolverPath()

virtual unsigned int sedris::seWorkspace::getMemoryModel (   )  const [virtual]
 

Returns the memory model in use by the workspace.

See also:
setMemoryModel()

virtual const char* sedris::seWorkspace::getName (   )  const [virtual]
 

virtual void sedris::seWorkspace::getOpenedTransmittal (  unsigned int  index,
seTransmittal &  xmtal
)  const [virtual]
 

Returns a handle to an opened transmittal by index. 

            seWorkspace wksp;
            ... open transmittals

            for (unsigned int i=0; i < wksp.getOpenedTransmittalCount(); i++)
            {
                seTransmittal xmtal;
                wksp.getOpenedTransmittal(i, xmtal);
                cout << xmtal.getFileName() << " is opened" << endl;
            }
See also:
getOpenedTransmittalCount()
Parameters:
index in: index of transmittal to return
xmtal in/out: the recipient transmittal handle

virtual unsigned int sedris::seWorkspace::getOpenedTransmittalCount (   )  const [virtual]
 

Returns the current number of opened transmittals in this workspace.

See also:
getOpenedTransmittal()

virtual bool sedris::seWorkspace::isValid (   )  const [virtual]
 

Returns true if this workspace handle is valid (workspace is opened). 

            seWorkspace wksp;
            ...
            if (wksp.isValid())
                cout << "Workspace is opened";

virtual void sedris::seWorkspace::open (  const char *  name = NULL,
const char *  params = NULL
)  [virtual]
 

Opens a previously closed workspace. 

            seWorkspace wksp("a name"); // implicit open()
            ...
            wksp.openTransmittalByFile(...);
            ...
            wksp.close();
            ...
            wksp.open("another name");
            wksp.openTransmittalByFile(...);
Note:
Normally you would not need to open() or close() workspaces. The constructor can take the same parameters given here, and the destructor takes care of the closing (if the workspace is still open).

If the workspace was already opened, an seException is thrown.

See also:
close()

virtual void sedris::seWorkspace::openTransmittalByFile (  const char *  file_name,
seTransmittal &  xmtal,
SE_Access_Mode  access_mode = SE_AC_MODE_READ_ONLY
)  [virtual]
 

Opens a transmittal by file using the access mode specified. This is the general way to open a transmittal by file. You can also use the convenience methods createTransmittal() and editTransmittal() to create and open transmittals for editing, respectively. 

            seWorkspace wksp;
            seTransmittal xmtal;
            seDRMTransmittalRoot root_obj;

            wksp.openTransmittalByFile("transmittals/test.stf", xmtal);
            cout << xmtal.getFileName() << " is now opened";
            xmtal.getRootObject(root_obj);
            ... process transmittal hierarchy
Note:
If no access mode parameter is provided, the transmittal is opened read only (SE_AC_MODE_READ_ONLY).
See also:
createTransmittal(), editTransmittal()
Parameters:
file_name in: file name and path of transmittal to open
xmtal in/out: the recipient transmittal handle
access_mode in (optional): access mode, use SE_AC_MODE_READ_ONLY, SE_AC_MODE_CREATE, SE_AC_MODE_UPDATE

virtual void sedris::seWorkspace::openTransmittalByURN (  const char *  xmtal_urn,
seTransmittal &  xmtal,
SE_Access_Mode  access_mode = SE_AC_MODE_READ_ONLY
)  [virtual]
 

Open a transmittal by its URN. The API uses resolver files to map a URN to a resource location (typically a file on a disk). See resolveTransmittalURN() for more information on resolver files.

Note:
URNs are assigned to transmittals by calling setURN() on transmittals opened in create or update mode.

This method is a convenience method to manually resolving a URN by calling resolveTransmittalURN(), and then calling openTransmittalByFile() with the resolved resource location.

See also:
seTransmittal::setURN(), resolveTransmittalURN()
Parameters:
xmtal_urn in: URN of transmittal to open
xmtal in/out: the recipient transmittal handle
access_mode in (optional): access mode, use SE_AC_MODE_READ_ONLY, SE_AC_MODE_CREATE, SE_AC_MODE_UPDATE
Returns:
true if successful

seWorkspace& sedris::seWorkspace::operator= (  const seWorkspace &   )  [inline, protected]
 

virtual const char* sedris::seWorkspace::resolveTransmittalURN (  const char *  xmtal_urn  )  [virtual]
 

Resolves a transmittal URN to a transmittal resource location. The API uses a search mechanism to look for resolver files with the appropriate mapping of a URN to a resource. The default extension for SEDRIS resolver files is ".rsl", and the default file name for SEDRIS resolver files is "sedris.rsl". The resolution process proceeds as follows until the URN is resolved:

  1. Use each opened transmittal's filename and replace their extension with ".rsl". For each transmittal, if a matching file is found, see if the resolution can be completed from its contents.
  2. Use the environment variable SEDRIS_RESOLVER_PATH to search for "sedris.rsl" in its list of search directories.
  3. Use the workspace's search paths (set with setResolverPath()) to look for "sedris.rsl" in its list of search directories.
An example line in a SEDRIS resolver file may look like: 
            TRANSMITTAL urn:sedris:xyzcorp:xyz_data_orlando:1 3.1:stf:3.1 file:///${CUR_RESOLVE_DIR}\xyz_mco.stf
        
            seWorkspace wksp;
            const char *file_path;

            if (wksp.resolveTransmittalURN("xyz_data_orlando", &file_path))
            {
                cout << "Transmittal is at " << file_path << endl;
            }

The format of a valid SEDRIS name is as follows: urn:sedris:<delegated_creation_authority>:<assigned_transmittal_name> [:<transmittal_version_serial>]

Note:
In the format shown above there must be no white space or carriage control characters within or between the sub-fields.
The format as described here is for cursory information only. Please consult the SEDRIS documentation set for a complete and formal description of the SEDRIS namespace and resolution process.

The first 11 characters are required fields that represent a sentinel for the SEDRIS namespace. These fields must be present for the name string to be considered valid.

The <delegated_creation_authority> is the string representing the portion of the SEDRIS namespace that has been delegated by the SEDRIS namespace registrar to the group, organization, or body that has authority for the assignment of transmittal named within the delegated namespace. This string may represent a sub-delegation by the registered authority to another group, organization or body.

The <assigned_transmittal_name> is the string representing a specific transmittal, and the optional <transmittal_version_serial> allows for a more specific designation of the transmittal to resolve. The rules governing the naming and versioning of SEDRIS transmittals are described more fully in the SEDRIS documentation set.

Warning:
The returned pointer should not be kept by the user since the next call to this method may change its contents.
See also:
setITRResolverPath(), openTransmittalByURN()
Parameters:
xmtal_urn in: transmittal URN to resolve
Returns:
the transmittal resource location if successful, an empty string otherwise

virtual void sedris::seWorkspace::setAccessModeInheritance (  bool  tf  )  [virtual]
 

Sets whether access modes are inherited by the automatic ITR resolution process. This flag indicates whether the access mode used when opening transmittals should be propagated to transmittals opened by the automatic ITR resolution process (see setITRBehaviour()). For example, if you open a transmittal in update mode, the access mode inheritance flag is set to true (i.e. to inherit the modes), and the ITR behaviour is set to automatically resolve, then all transmittals being referenced will also be opened in update mode. If this flag is set to false, then (if automatic resolution is enabled) ITR references will be opened in read only mode.

Note:
If you are updating a transmittal, then you would probably want to set this flag to true so that dependent transmittals are also opened in update mode.
Warning:
Setting this flag to true may cause changes (when in update mode) to more than one transmittal.
Parameters:
tf in: boolean flag

virtual void sedris::seWorkspace::setITRBehaviour (  SE_ITR_Behaviour  itr_behaviour  )  [virtual]
 

Sets the ITR behaviour to use in the workspace from now on. The ITR behaviour determines how iterators and objects behave when they encounter an ITR reference. See seIterator::getNext() for information on iterator behaviour. Also see the documentation for the SE_ITR_Behaviour type for more information.

Note:
The default behaviour is to resolve objects.
See also:
seIterator::getNext(), createUnresolvedObject(), seObject::isResolved()
Parameters:
itr_behaviour in: the new ITR behaviour to use

virtual void sedris::seWorkspace::setITRResolverPath (  const char *  new_path  )  [virtual]
 

Sets the ITR resolver path to use in the workspace from now on. The resolver path is used to find resolver files when resolving a transmittal URN to an actual resource (typically a disk file). You may specify multiple directories by separating them with colons (:) in Unix systems or semicolons (;) in Win32 systems.

Parameters:
new_path: the new resolver path to use

virtual void sedris::seWorkspace::setMemoryModel (  unsigned int  mem_model  )  [virtual]
 

Sets the memory model used by transmittals. The operation of the memory model is transmittal implementation dependent. The default value is 0, which lets the transmittal implementation to choose its own value.

Note:
A memory model is only applicable when a transmittal is opened. It has no effect on the transmittal afterwards.
Warning:
This method is experimental.
Parameters:
mem_model in: new memory model to use

virtual void sedris::seWorkspace::setName (  const char *  name  )  [virtual]
 

Set the workspace name. Note that workspaces can have a name but the names are inconsequential and are not required for normal operation. An application can set the name to whatever string it wants.

Note:
If no name is provided for the workspace, a default name will be used.
Parameters:
name in: the name for the workspace

The documentation for this class was generated from the following file:
SEDRIS Transmittal Access C++ API 4.0.0 beta - 14 Jul 2004
Copyright © 2004 SEDRIS™ Docs by Doxygen 1.3.2