com.plumtree.remote.prc
Interface IDocumentManager

public interface IDocumentManager

Interface that allows remote services to create new documents in the portal Knowledge Directory.

Method Summary

void	addDocuments(int documentID, int[] destinationFolderIDs) Adds documents to the portal. Note that this does not duplicate the document file itself, only links to the document from the portal.
IDocumentQuery	createQuery(int folderID) Factory method to create a document query on a specified document folder.
IRemoteDocument	createRemoteDocument(int[] folderIDs, int dataSourceID, java.lang.String location, boolean mergeACLs) Creates a new remote document.
IRemoteDocument	createRemoteDocument(int parentFolderID, int dataSourceID, java.lang.String location) Creates a new remote document.
IWebLinkDocument	createWebLinkDocument(int[] folderIDs, int dataSourceID, java.lang.String link, boolean mergeACLs) Creates a new Web link document.
IWebLinkDocument	createWebLinkDocument(int parentFolderID, int dataSourceID, java.lang.String link) Creates a new Web link document.
IACL	queryACL(int documentID) Retrieves an ACL (Access Control List) for managing the security on a document.
IObjectQuery	queryContainingFolders(int documentID) Queries for all folders which contain a specific document
IDocumentProperties	queryDocumentProperties(int documentID) Queries the properties of a document.
void	removeDocuments(int[] documentIDs) Removes documents from the portal. Note that this does not remove the document file itself, only the link to the document from the portal.
void	setBrokenLinkDeletionTime(int documentID, TimeInterval deletionTime) Sets the time interval after which a broken link document will be deleted.
void	setExpirationDate(int documentID, java.util.Date expires) Sets the date at which to expire this document.
void	setNeverExpires(int documentID) Sets a document to be never expired.
void	setRefreshRate(int documentID, TimeInterval refreshInterval, boolean doNotRefreshProperties) Sets the document refresh rate, which determines how often a document and its properties will get refreshed.
void	updateACL(int documentID, IACL acl) Updates the ACL (Access Control List) on a document.
void	updateDocumentProperties(int documentID, IDocumentProperties properties) Updates the properties of a document.

Method Detail

createRemoteDocument

public IRemoteDocument createRemoteDocument(int parentFolderID,
                                            int dataSourceID,
                                            java.lang.String location)

Creates a new remote document. The document will not be saved in the portal Knowledge Directory until the save() method is called on the IDocument object.

Parameters:

parentFolderID - the ID of the directory folder in which to create the new document

dataSourceID - the ID of the Data Source associated with the new document

location - the location string that will be passed to the remote crawler to indicate which document to retrieve. Further notes on location: this is the same value which would be returned in the location field of com.plumtree.remote.crawler.ChildDocument and then passed to the DataSource in com.plumtree.remote.crawler.IDocumentProvider#attachToDocument. The location string could be a full path for a file crawler; a concatenation of schema, table name, and primary key for a database crawler; a concatenation of database name, view name, and document unique id for a Notes crawler; or a application-specific string for a custom crawler.

 //get the document manager.....
 int folderID = 20; //get from the query string from mousing over the directory folder in the ui
 int dataSourceID = 30; //get from the query string from mousing over the data source in the ui
 //location of a file; the format of the location string is data-source specific
 String location =  "\\\\MyServer\\share\\Portlet FAQ and Price list.doc"  ;
 IRemoteDocument doc = documentManager.createRemoteDocument(folderID, dataSourceID, location);
 //set the override name and description- otherwise the value would be taken from the accessor
 doc.setOverrideName("Portlet Price List");
 doc.setOverrideDescription("Portlet Prices and FAQs");
 //set the type- in this case, a word doc in the MIME namespace
 doc.setType("http://www.plumtree.com/dtm/mime", "application/msword");
 //set the docID to a negative number to check for failure
 int docID = -1;
 try
 }
   docID = documentManager.save();
 }
 catch (MalformedURLException e)
 {
  //if the query interface URL was not valid
  e.printStackTrace();
 }
 catch (PortalException pe)
 {
  //if the operation resulted in an error in the portal
  pe.printStackTrace();
 }
 catch (RemoteException re)
 {
  //if there was a communication problem during the execution of the remote method call
  re.printStackTrace();
 }
 //process docID as desired......
 

Returns:

the new document

createWebLinkDocument

public IWebLinkDocument createWebLinkDocument(int parentFolderID,
                                              int dataSourceID,
                                              java.lang.String link)

Creates a new Web link document. The document will not be saved in the portal Knowledge Directory until the save() method is called on the Document object.

Parameters:

parentFolderID - the ID of the directory folder in which to create the new document

dataSourceID - the ID of the Data Source associated with the new document

link - the Web location of the new document; must be a URL

Returns:

the new document

createRemoteDocument

public IRemoteDocument createRemoteDocument(int[] folderIDs,
                                            int dataSourceID,
                                            java.lang.String location,
                                            boolean mergeACLs)

Creates a new remote document. The document will not be saved in the portal Knowledge Directory until the save() method is called on the IDocument object.

Parameters:

folderIDs - the IDs of the directory folders in which to add the new document.

dataSourceID - the ID of the Data Source associated with the new document.

location - the location string that will be passed to the remote crawler to indicate which document to retrieve; can be a URL

mergeACLs - true to use the merged ACLs of the parent folders, false to use the default ACL. Further notes on location: this is the same value which would be returned in the location field of com.plumtree.remote.crawler.ChildDocument and then passed to the DataSource in com.plumtree.remote.crawler.IDocumentProvider#attachToDocument. The location string could be a full path for a file crawler; a concatenation of schema, table name, and primary key for a database crawler; a concatenation of database name, view name, and document unique id for a Notes crawler; or a application-specific string for a custom crawler.

 //get the document manager.....
 int[] folderIDs = {20,25,20}; //get from the query string from mousing over the directory folders in the ui
 int dataSourceID = 30; //get from the query string from mousing over the data source in the ui
 //location of a file; the format of the location string is data-source specific
 String location =  "\\\\MyServer\\share\\Portlet FAQ and Price list.doc"  ;
 IRemoteDocument doc = documentManager.createRemoteDocument(folderIDs, dataSourceID, location, true);
 //set the override name and description- otherwise the value would be taken from the accessor
 doc.setOverrideName("Portlet Price List");
 doc.setOverrideDescription("Portlet Prices and FAQs");
 //set the type- in this case, a word doc in the MIME namespace
 doc.setType("http://www.plumtree.com/dtm/mime", "application/msword");
 //set the docID to a negative number to check for failure
 int docID = -1;
 try
 }
   docID = documentManager.save();
 }
 catch (MalformedURLException e)
 {
  //if the query interface URL was not valid
  e.printStackTrace();
 }
 catch (PortalException pe)
 {
  //if the operation resulted in an error in the portal
  pe.printStackTrace();
 }
 catch (RemoteException re)
 {
  //if there was a communication problem during the execution of the remote method call
  re.printStackTrace();
 }
 //process docID as desired......
 

Returns:

the new document

createWebLinkDocument

public IWebLinkDocument createWebLinkDocument(int[] folderIDs,
                                              int dataSourceID,
                                              java.lang.String link,
                                              boolean mergeACLs)

Creates a new Web link document. The document will not be saved in the portal Knowledge Directory until the save() method is called on the Document object.

Parameters:

folderIDs - the IDs of the directory folders in which to add the new document

dataSourceID - the ID of the Data Source associated with the new document

link - the Web location of the new document; must be a URL

mergeACLs - true to use the merged ACLs of the parent folders, false to use the default ACL.

Returns:

the new document

queryDocumentProperties

public IDocumentProperties queryDocumentProperties(int documentID)
                                            throws PortalException,
                                                   java.rmi.RemoteException

Queries the properties of a document.

Parameters:

documentID - the document ID of the document for which to query the properties

Returns:

the document properties

Throws:

PortalException - if the operation resulted in an error on the portal

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call

updateDocumentProperties

public void updateDocumentProperties(int documentID,
                                     IDocumentProperties properties)
                              throws PortalException,
                                     java.rmi.RemoteException

Updates the properties of a document.

Parameters:

documentID - the document ID of the document to update

properties - the properties to update the document with. If any intrinsic properties have been deleted from the portal, the corresponding property must be removed from the DocumentTypeMap or the update will fail.

Throws:

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call

PortalException - if the operation resulted in an error on the portal.

java.lang.NullPointerException - if properties is null

setRefreshRate

public void setRefreshRate(int documentID,
                           TimeInterval refreshInterval,
                           boolean doNotRefreshProperties)
                    throws PortalException,
                           java.rmi.RemoteException

Sets the document refresh rate, which determines how often a document and its properties will get refreshed. If the boolean value of doNotRefreshProperties is set to true, only the validity of the link to this document will be confirmed and no document properties will be refreshed.
The numeric component of the resfresh interval must be between 1 to 999, otherwise an IllegalArgumentException will be thrown.
Setting the refreshInterval to TimeInterval.INFINITE will set the document to be never refreshed.
The default refresh rate for a document is set by the document Crawler.

Parameters:

documentID - ID of the document to set refresh rate; cannot be negative.

refreshInterval - time interval specifying the refresh interval value and unit. The numeric component must be between 1 to 999, otherwise an IllegalArgumentException will be thrown. Setting the refreshInterval to TimeInterval.INFINITE will cause the document to never get refreshed.

doNotRefreshProperties - if set to true, only the link to the document will be confirmed, and no document properties will be refreshed, otherwise false.

Throws:

PortalException - if the document ID is invalid, or if the operation resulted in an error on the portal.

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call

java.lang.IllegalArgumentException - if the documentID is negative, or the numeric component of the refreshInterval is not between 1 to 999.

java.lang.NullPointerException - if timeInterval or the unit component of the timeInterval is null.

setBrokenLinkDeletionTime

public void setBrokenLinkDeletionTime(int documentID,
                                      TimeInterval deletionTime)
                               throws PortalException,
                                      java.rmi.RemoteException

Sets the time interval after which a broken link document will be deleted. Setting the deletionTime to TimeInterval.INFINITE will cause a broken link document to be never deleted.
The numeric component of the deletionTime must be between 1 to 999, otherwise an IllegalArgumentException will be thrown.
The default broken link deletion time for a document is set by the document crawler.

Parameters:

documentID - ID of the document to set broken link deletion time; cannot be negative.

deletionTime - time interval after which a missing document will be deleted. The numeric component must be between 1 to 999, otherwise an IllegalArgumentException will be thrown. Setting the deletionTime to TimeInterval.INFINITE will cause the document to be never deleted.

Throws:

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call.

PortalException - if the document ID is invalid, or if the operation resulted in an error on the portal.

java.lang.IllegalArgumentException - if the documentID is negative, or the numeric component of the refreshInterval is not between 1 to 999.

java.lang.NullPointerException - if deletionTime or the unit component of the deletionTime is null.

setExpirationDate

public void setExpirationDate(int documentID,
                              java.util.Date expires)
                       throws PortalException,
                              java.rmi.RemoteException

Sets the date at which to expire this document.
The default expiration date for a document is set by the document crawler.

Parameters:

documentID - ID of the document to set expiration on.

expires - the time at which the document is set to expire. Cannot be null.

Throws:

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call

PortalException - if the document ID is invalid, or if the operation resulted in an error on the portal.

java.lang.IllegalArgumentException - if the documentID is negative.

setNeverExpires

public void setNeverExpires(int documentID)
                     throws PortalException,
                            java.rmi.RemoteException

Sets a document to be never expired.
The default expiration date for a document is set by the document crawler.

Parameters:

documentID - ID of the document to set expiration on.

Throws:

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call

PortalException - if the document ID is invalid, or if the operation resulted in an error on the portal.

java.lang.IllegalArgumentException - if the documentID is negative.

removeDocuments

public void removeDocuments(int[] documentIDs)
                     throws PortalException,
                            java.rmi.RemoteException

Removes documents from the portal.
Note that this does not remove the document file itself, only the link to the document from the portal. Note: As this method performs multiple operations, any exception thrown relating to these will have details of each failure.

Parameters:

documentIDs - the IDs of the documents to remove

Throws:

PortalException - if the operation resulted in an error on the portal

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call

addDocuments

public void addDocuments(int documentID,
                         int[] destinationFolderIDs)
                  throws PortalException,
                         java.rmi.RemoteException

Adds documents to the portal.
Note that this does not duplicate the document file itself, only links to the document from the portal. Note: As this method performs multiple operations, any exception thrown relating to these will have details of each failure.

Parameters:

documentID - the ID of the document to add

destinationFolderIDs - the IDs of the folders to add the document to

Throws:

PortalException - if the operation resulted in an error on the portal

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call

createQuery

public IDocumentQuery createQuery(int folderID)

Factory method to create a document query on a specified document folder. The created query parameters default to start row 0, maximum of 100 results, show unapproved documents, sort by Document ID and no filters.

Parameters:

folderID - folder ID to query

Returns:

a document query object

queryContainingFolders

public IObjectQuery queryContainingFolders(int documentID)
                                    throws PortalException,
                                           java.rmi.RemoteException

Queries for all folders which contain a specific document

Parameters:

documentID - the ID of the document to query for

Returns:

Containing folder objects

Throws:

PortalException - if the operation resulted in an error on the portal

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call

java.lang.IllegalArgumentException - if passed an invalid document ID

queryACL

public IACL queryACL(int documentID)
              throws java.net.MalformedURLException,
                     PortalException,
                     java.rmi.RemoteException

Retrieves an ACL (Access Control List) for managing the security on a document.

Parameters:

documentID - the document ID of the object for which to retrieve the ACL

Returns:

the document's ACL

Throws:

java.net.MalformedURLException - if the query interface URL is not valid

java.lang.IllegalArgumentException - if passed an invalid document ID

PortalException - if the operation resulted in an error on the portal

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call

updateACL

public void updateACL(int documentID,
                      IACL acl)
               throws java.net.MalformedURLException,
                      PortalException,
                      java.rmi.RemoteException

Updates the ACL (Access Control List) on a document. You can only update the ACL on a document with an ACL which was retrieved from the same document

Parameters:

documentID - the document ID for which to set the ACL

acl - the ACL to set on the document

Throws:

java.net.MalformedURLException - if the query interface URL is not valid

java.lang.IllegalArgumentException - if passed an invalid document ID

PortalException - if the operation resulted in an error on the portal

java.rmi.RemoteException - if there is a communication problem during the execution of the remote method call

ACLEntryReadOnlyException - if the ACL contains read-only ACLEntry's which have been modified