Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## com.fujitsu.iflow.model.wfadapter
Interface DocRepository

public interface DocRepository

Manages the interaction between the client and the Document Management System (DMS), including checking in, checking out and viewing attachment files. It also maintains the list of files checked out by a user for editing.

In addition, this interface can be used to create and maintain the list of user-defined document types, as well as associating them with the application that is used to open or editing documents.

Usually, in the off-the-shelf implementation, only one `DocRepository` object is required per client. In addition, the current implementation considers all files that are checked into a process definition or into a process instance in structural edit-mode as "forms" and all files checked into a running process as "attachments."

This interface does not need to be implemented with the above specific details. All methods in this interface can be used with any type of file in either a process definition or process instance.

`String` parameters of all methods in this class have a length limit. This limit is documented in the Javadoc comment for every parameter. If the length of a value supplied for such a parameter exceeds this limit or the value is `null`, an exception is thrown.

If the signature of a method does not allow throwing any exception, any value supplied to this method that exceeds the length limit is truncated to the maximum length supported. `null` values are ignored in this case. Any method’s behaviour that differs from the behaviour described above is explained in this method’s Javadoc comment.

Exceptions are subclasses of `ModelException`. For future compatibility, only `ModelException` should be caught explicitly.

Method Summary
`void` | `addDocType(java.lang.String name, java.lang.String extList, java.lang.String program)` Adds a new association between a document type and the application that opens it.
`void` | `checkIn(Document doc)` Uploads the file to the server if the document was previously checked out for editing.
`void` | `checkIn(java.lang.String documentPath)` Uploads the file to the server if the document was previously checked out for editing.
`void` | `checkInNew(java.lang.String path, byte[] contents, boolean overwrite)` Uploads a new file to the specified path in the DMS.
`void` | `checkInNew(java.lang.String path, java.lang.String localFile, boolean overwrite)` Uploads a new file to the specified path in the DMS.
`java.io.File` | `checkOut(java.lang.String pathname, boolean lock)` Returns the file stored at the specified path in the DMS.
`void` | `checkOut(java.lang.String pathname, java.io.File file, boolean lock)` Returns the file stored at the specified path in the DMS.
`void` | `deleteDocument(java.lang.String path)` Deletes the specified file from the DMS.
`DMS` | `getDMS()` Returns the `DMS` (interface) object being managed by the document repository.
`DocType` | `getDocType(java.lang.String name)` Returns the document type with the given name.
`DocType[]` | `getDocTypes()` Returns all document type associations that have been defined for a client machine, or an empty array if there are none.
`Document` | `getDocument(java.lang.String docPath)` Returns a `Document` object that corresponds to a file in a Document Management System (DMS).
`Folder` | `getFolder(java.lang.String folderPath)` Returns a `Folder` object that corresponds to a folder in a Document Management System (DMS).
`Document[]` | `getLockedDocs()` Returns the list of files locked by the logged-in user for editing, or an empty array if there are none.
`Folder` | `getRootFolder(DMS dms)` Returns the folder that represents the root directory of the specified `DMS` object.
`boolean` | `hasType(java.lang.String type)` Returns `true` if the file extension type has been associated with an application for opening files with this extension.
`java.lang.String` | `pathToLocalHostFormat(java.lang.String path)` Converts the path to the local file system path format.
`void` | `removeDocType(java.lang.String name)` Removes the specified user-defined document type.
`void` | `viewDoc(java.lang.String pathname, boolean lock)` Checks out and opens the file stored at the specified path in the DMS.

Method Detail

### getFolder

    public Folder getFolder(java.lang.String folderPath)

  Returns a `Folder` object that corresponds to a folder in a Document Management System (DMS).

  Parameters:
    `folderPath` - The path of the folder in the DMS.
  Returns:
    `Folder` object

### getDocument

    public Document getDocument(java.lang.String docPath)
                         throws ModelInternalException

  Returns a `Document` object that corresponds to a file in a Document Management System (DMS).

  Parameters:
    `docPath` - The path of the file in the DMS.
  Returns:
    `Document` object
  Throws:
    `ModelInternalException` - Thrown if setting of the path fails.

### getRootFolder

    public Folder getRootFolder(DMS dms)

  Returns the folder that represents the root directory of the specified `DMS` object.

  The `Folder` object obtained will contain the list of all DMS root directories listed in the "twf.ini" file. To retrieve the path of the root directories, use the returned `Folder` object as described in the following code sample. Calling the method `Folder.getPath` will return an empty `String`.

  Sample for retrieving the root directories:

       DMS dms = docRepos.getDMS();
       Folder folder = (Folder) docRepos.getRootFolder(dms);
       DMSObject[] list = folder.getContents();
       for(int i = 0;i < list.length;i++){
          String path = list[i].getPath();
          // .... do some thing .. //
       }

  Parameters:
    `dms` - `DMS` object
  Returns:
    `Folder` object

### getDMS

    public DMS getDMS()

  Returns the `DMS` (interface) object being managed by the document repository. This DMS was originally created by the `WFObjectFactory` and used as a parameter in getting this `DocRepository` object. `getDMS` returns a reference to that DMS later.

  Returns:
    The DMS being managed by the document repository.

### viewDoc

    public void viewDoc(java.lang.String pathname,
                        boolean lock)
                 throws DMSException,
                        ModelInternalException

  Checks out and opens the file stored at the specified path in the DMS.

  The `lock` parameter is used to control whether other users can access the file while it is checked out. If set to `false`, other users can also retrieve the file. In this case, the file cannot be placed back into the DMS. If set to `true`, no other user can access the file until the user who checked out the file checks it in again.

  Parameters:
    `pathname` - The path of the file in the DMS.
    `lock` - `true` to prevent other users accessing the file, `false` otherwise.
  Throws:
    `ModelInternalException`
    `DMSException`
  See Also:
    `checkOut(java.lang.String, boolean)`, `addDocType(java.lang.String, java.lang.String, java.lang.String)`

### checkIn

    public void checkIn(Document doc)
                 throws DMSException,
                        ModelInternalException

  Uploads the file to the server if the document was previously checked out for editing. This action removes the lock on the file so that other users can check out the file.

  Parameters:
    `doc` - The file to be uploaded to the server. A document object must be created for the document before it can be checked in.
  Throws:
    `ModelInternalException`
    `DMSException`

### checkIn

    public void checkIn(java.lang.String documentPath)
                 throws DMSException,
                        ModelInternalException

  Uploads the file to the server if the document was previously checked out for editing. This action removes the lock on the file so that other users can check out the file out. The `String` parameter is the path of the document in the server file system.

  Parameters:
    `documentPath` - Path of the document to be uploaded to the server.
  Throws:
    `DMSException`
    `ModelInternalException`

### checkInNew

    public void checkInNew(java.lang.String path,
                           byte[] contents,
                           boolean overwrite)
                    throws DMSException,
                           ModelInternalException

  Uploads a new file to the specified path in the DMS. This method adds forms to process definitions.

  The path of file must not be longer than specified by `DMS.MAX_PATH_LENGTH`.

  Parameters:
    `path` - The path in the DMS for the file to be uploaded to.
    `contents` - The contents of the file to be uploaded to the server.
    `overwrite` - `true` if an existing file with the same name is to be overwritten, `false` otherwise.
  Throws:
    `DMSException`
    `ModelInternalException`

### checkInNew

    public void checkInNew(java.lang.String path,
                           java.lang.String localFile,
                           boolean overwrite)
                    throws DMSException,
                           ModelInternalException

  Uploads a new file to the specified path in the DMS. This method adds attachments to process instances.

  The path of files (`path` and `localFile`) must not be longer than specified by `DMS.MAX_PATH_LENGTH`.

  Parameters:
    `path` - The path in the DMS for the file to be uploaded to.
    `localFile` - The fully qualified path and file name on the client machine where the file resides. This file will be copied into the DMS, the original files will remain on the client machine.
    `overwrite` - `true` if an existing file with the same name is to be overwritten, `false` otherwise.
  Throws:
    `DMSException`
    `ModelInternalException`

### getDocType

    public DocType getDocType(java.lang.String name)

  Returns the document type with the given name. If the name is not found, a null pointer is returned. This `DocType` object associates the file type extension(s) with the executable program that opens such files.

  Parameters:
    `name` - The name of the document type.
  Returns:
    Associated `DocType` object
  See Also:
    `addDocType(String, String, String)`

### checkOut

    public java.io.File checkOut(java.lang.String pathname,
                                 boolean lock)
                          throws DMSException,
                                 ModelInternalException

  Returns the file stored at the specified path in the DMS.

  The `lock` parameter is used to control whether other users can access the file while it is checked out. If set to `false`, other users can also retrieve the file. In this case, the file cannot be placed back into the DMS. If set to `true`, no other user can access the file until the user who checked out the file checks it in again.

  The path name must not be longer than specified by `DMS.MAX_PATH_LENGTH`.

  Parameters:
    `pathname` - The path of the file (within the DMS) to be downloaded.
    `lock` - `true` to prevent other users accessing the file, `false` otherwise.
  Returns:
    `File` object referred to by the path
  Throws:
    `DMSException`
    `ModelInternalException`
  See Also:
    `viewDoc(String, boolean)`

### checkOut

    public void checkOut(java.lang.String pathname,
                         java.io.File file,
                         boolean lock)
                  throws DMSException,
                         ModelInternalException

  Returns the file stored at the specified path in the DMS.

  The `lock` parameter is used to control whether other users can access the file while it is checked out. If set to `false`, other users can also retrieve the file. In this case, the file cannot be placed back into the DMS. If set to `true`, no other user can access the file until the user who checked out the file checks it in again.

  The path name must not be longer than specified by `DMS.MAX_PATH_LENGTH`.

  Parameters:
    `pathname` - The path of the file (within the DMS) to be downloaded
    `file` - The file name of this downloaded file on the client machine.
    `lock` - `true` to prevent other users accessing the file, `false` otherwise.
  Throws:
    `DMSException`
    `ModelInternalException`
  See Also:
    `viewDoc(String, boolean)`

### removeDocType

    public void removeDocType(java.lang.String name)
                       throws ModelInternalException

  Removes the specified user-defined document type. This removes the association between that type and the corresponding executable program used for opening files of this type.

  Parameters:
    `name` - The name of document type to be removed.
  Throws:
    `ModelInternalException`
  See Also:
    `addDocType(String, String, String)`

### hasType

    public boolean hasType(java.lang.String type)
                    throws ModelInternalException

  Returns `true` if the file extension type has been associated with an application for opening files with this extension. This association is applied locally to the system this class is run on.

  Parameters:
    `type` - The file extension
  Returns:
    `true` if the file extension type has an association, `false` otherwise.
  Throws:
    `ModelInternalException`

### addDocType

    public void addDocType(java.lang.String name,
                           java.lang.String extList,
                           java.lang.String program)
                    throws ModelInternalException

  Adds a new association between a document type and the application that opens it. As specified in the parameters, adds the user-defined attachment type, the list of extensions, and the association between the type and the executable program used for opening the attachments of this type. This association is applied locally to the system this class is run on.

  The name must not contain any spaces. For separating words, use the underscore character.

  Parameters:
    `name` - The name of the document type, for example "ASCII_Documents".
    `extList` - A space- or comma-separated list of file extensions identifying the type of application, for example "txt bat".
    `program` - The fully qualified drive and path followed by the application file name used on the client machine to open files of the given type. For example "C:\winnt\notepad.exe". The directory delimiter must be appropriate for the operating system on the local system.
  Throws:
    `ModelInternalException`

### pathToLocalHostFormat

    public java.lang.String pathToLocalHostFormat(java.lang.String path)
                                           throws ModelInternalException

  Converts the path to the local file system path format. The local file system path format may be different on different machines with regard to directory separation character used in the DMS.

  The separation character is based on the DMS and/or operating system. In cases where the DMS is the operating system file system, it is usually a slash (/) or a backslash (\).

  Parameters:
    `path` - The path to be converted to the local file system path format.
  Returns:
    The path in the local file system format.
  Throws:
    `ModelInternalException`

### getDocTypes

    public DocType[] getDocTypes()
                          throws ModelInternalException

  Returns all document type associations that have been defined for a client machine, or an empty array if there are none. The associations apply to the machine this class is run on, not to the logged-in user.

  Returns:
    An array of all the user-defined `DocType` objects.
  Throws:
    `ModelInternalException`
  See Also:
    `addDocType(java.lang.String, java.lang.String, java.lang.String)`

### getLockedDocs

    public Document[] getLockedDocs()
                             throws ModelInternalException

  Returns the list of files locked by the logged-in user for editing, or an empty array if there are none. This is a comprehensive list, regardless of the process instances the files have been associated with.

  Returns:
    array of `Document` objects representing the files the user has checked out for editing.
  Throws:
    `ModelInternalException`

### deleteDocument

    public void deleteDocument(java.lang.String path)
                        throws ModelException

  Deletes the specified file from the DMS. Files can also be deleted if they are locked by another user.

  The path of file must not be longer than specified by `DMS.MAX_PATH_LENGTH`.

  Parameters:
    `path` - Full path of the document.
  Throws:
    `ModelException`

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD