com.filenet.api.core
Interface Folder

All Superinterfaces:
Containable, EngineObject, IndependentlyPersistableObject, IndependentObject, Replicable, RepositoryObject, java.io.Serializable, Subscribable

public interface Folder
extends RepositoryObject, Containable, Replicable, Subscribable, IndependentlyPersistableObject

Represents a container that can hold other Containable subclasses, but cannot have content data of its own. Although Folder objects and their subclasses can be referentially contained, they are the only Containable subclass that can be directly contained (in a Folder). All other Containable subclasses are referentially contained using the ReferentialContainmentRelationship or DynamicReferentialContainmentRelationship classes.

Note: Folders that are referentially contained cannot participate in hierarchy index searches.

The container hierarchy is a one-to-many relationship: a folder can have many child folders, but a child folder can have only one parent folder. At the top of the container hierarchy is an automatically-created root folder. Use ObjectStore.get_RootFolder to get a reference to the root folder.

Folders are not versionable.

Metadata

Auditable: true
AllowsInstances: true
AllowsSubClasses: true
ClassDefinitionName: ReplicableClassDefinition
IsDependent: false
IsHidden: false
Name: FolderName
Searchable: true
StorageType: ObjectStore
SuperclassName: Containable

See Also:
ReferentialContainmentRelationship, DynamicReferentialContainmentRelationship

Method Summary
 void applySecurityTemplate(Id applyStateId)
          Applies a security policy template to the given object.
 void changeClass(java.lang.String className)
          Changes the class of a Content Engine object.
 Folder createSubFolder(java.lang.String name)
          Creates a directly-contained subfolder of this folder.
 ReferentialContainmentRelationship file(IndependentlyPersistableObject containee, AutoUniqueName autoUniqueName, java.lang.String containmentName, DefineSecurityParentage defineSecurityParentage)
          Files an instance of a Containable subclass to this folder.
 DocumentSet get_ContainedDocuments()
          Returns the value of the ContainedDocuments property.
 ReferentialContainmentRelationshipSet get_Containees()
          Returns the value of the Containees property.
 java.lang.String get_FolderName()
          Returns the value of the FolderName property.
 Id get_IndexationId()
          Returns the value of the IndexationId property.
 java.lang.Boolean get_InheritParentPermissions()
          Returns the value of the InheritParentPermissions property.
 Folder get_Parent()
          Returns the value of the Parent property.
 java.lang.String get_PathName()
          Returns the value of the PathName property.
 FolderSet get_SubFolders()
          Returns the value of the SubFolders property.
 InstanceWorkflowSubscriptionSet get_WorkflowSubscriptions()
          Returns the value of the WorkflowSubscriptions property.
 java.lang.Boolean isLocked()
          Queries this object's lock state.
 void lock(int timeout, java.lang.String owner)
          Sets a new lock or updates an existing lock on the object.
 void move(Folder targetFolder)
          Moves this folder and all of its subfolders and contents from its current parent folder to the target parent folder specified.
 void set_FolderName(java.lang.String value)
          Sets the value of the FolderName property.
 void set_InheritParentPermissions(java.lang.Boolean value)
          Sets the value of the InheritParentPermissions property.
 void set_Parent(Folder value)
          Sets the value of the Parent property.
 ReferentialContainmentRelationship unfile(IndependentlyPersistableObject containee)
          Removes the specified containee from this folder.
 ReferentialContainmentRelationship unfile(java.lang.String containmentName)
          Unfile the object using a path specification.
 void unlock()
          Explicitly removes the lock from this object.
 void updateLock(long timeout)
          Adjusts the timeout period of the lock on this object.
 
Methods inherited from interface com.filenet.api.core.RepositoryObject
getObjectStore
 
Methods inherited from interface com.filenet.api.core.Containable
get_ActiveMarkings, get_Annotations, get_AuditedEvents, get_Containers, get_Creator, get_DateCreated, get_DateLastModified, get_Id, get_LastModifier, get_LockOwner, get_LockTimeout, get_LockToken, get_Name, get_Owner, get_Permissions, get_SecurityPolicy, set_Creator, set_DateCreated, set_DateLastModified, set_LastModifier, set_Owner, set_Permissions, set_SecurityPolicy
 
Methods inherited from interface com.filenet.api.replication.Replicable
get_ExternalReplicaIdentities, get_ReplicationGroup, set_ExternalReplicaIdentities, set_ReplicationGroup
 
Methods inherited from interface com.filenet.api.core.Subscribable
raiseEvent
 
Methods inherited from interface com.filenet.api.core.IndependentlyPersistableObject
addPendingAction, clearPendingActions, delete, getAccessAllowed, getPendingActions, getUpdateSequenceNumber, isCurrent, save, save, setUpdateSequenceNumber
 
Methods inherited from interface com.filenet.api.core.IndependentObject
fetchProperties, fetchProperties, fetchProperty, fetchProperty, getObjectReference, refresh, refresh, refresh
 
Methods inherited from interface com.filenet.api.core.EngineObject
get_ClassDescription, getClassName, getConnection, getProperties, getSuperClasses
 

Method Detail

get_Parent

Folder get_Parent()
Returns the value of the Parent property. For more information, see Parent Property.


set_Parent

void set_Parent(Folder value)
Sets the value of the Parent property. For more information, see Parent Property.


get_Containees

ReferentialContainmentRelationshipSet get_Containees()
Returns the value of the Containees property. For more information, see Containees Property.


get_FolderName

java.lang.String get_FolderName()
Returns the value of the FolderName property. For more information, see FolderName Property.


set_FolderName

void set_FolderName(java.lang.String value)
Sets the value of the FolderName property. For more information, see FolderName Property.


get_SubFolders

FolderSet get_SubFolders()
Returns the value of the SubFolders property. For more information, see SubFolders Property.


get_PathName

java.lang.String get_PathName()
Returns the value of the PathName property. For more information, see PathName Property.


get_InheritParentPermissions

java.lang.Boolean get_InheritParentPermissions()
Returns the value of the InheritParentPermissions property. For more information, see InheritParentPermissions Property.


set_InheritParentPermissions

void set_InheritParentPermissions(java.lang.Boolean value)
Sets the value of the InheritParentPermissions property. For more information, see InheritParentPermissions Property.


get_ContainedDocuments

DocumentSet get_ContainedDocuments()
Returns the value of the ContainedDocuments property. For more information, see ContainedDocuments Property.


get_WorkflowSubscriptions

InstanceWorkflowSubscriptionSet get_WorkflowSubscriptions()
Returns the value of the WorkflowSubscriptions property. For more information, see WorkflowSubscriptions Property.


get_IndexationId

Id get_IndexationId()
Returns the value of the IndexationId property. For more information, see IndexationId Property.


unfile

ReferentialContainmentRelationship unfile(IndependentlyPersistableObject containee)
Removes the specified containee from this folder. This does not delete the containee object from the object store.

You then need to call the save method on the returned ReferentialContainmentRelationship object. This method is equivalent to getting the ReferentialContainmentRelationship object (returned) and deleting it.

Parameters:
containee - The containment name of the object to remove.
Returns:
The ReferentialContainmentRelationship object for the containee to remove.
See Also:
file

isLocked

java.lang.Boolean isLocked()
Queries this object's lock state. This helper method examines the object's lock-related properties and determines the object's lock state. An alternative approach is to call the lock method and handle any exception thrown if the method fails.

Note that this method returns an approximation of the locked state at the time of the call. Once this method executes and returns the value, the object's lock state could be immediately changed by another application's call to the lock method or the lock could expire.

Before calling this method, make sure that the object's LockToken, LockTimeout, and DateLastModified properties have relatively fresh values. If any of those properties is missing, they are silently fetched from the server and added to the object's property cache.

The isLocked method returns false if the LockTimeout property is not set or if the lock has expired. The lock is determined to be expired if the DateLastModified property value plus the number of seconds specified by the LockTimeout property is less than the current system time. (All millisecond components are dropped from the calculation.) If the DateLastModified property is not set, this method returns false because the check against the lock timeout value or the lock token will yield null, meaning that the object is not locked. As soon as some action locks the object, the DateLastModified property will be updated and can then used for the expiration calculation.

Note: To successfully run isLocked and other cooperative locking methods, system clocks on the IBM FileNet P8 platform engine machines must be synchronized. The calculation performed by the isLocked() method is done on the client system. If the client and server machine clocks are not synchronized, the result of this calculation might be incorrect.

Returns:
true if this object is locked; otherwise, returns false.

changeClass

void changeClass(java.lang.String className)
Changes the class of a Content Engine object. The new class must already exist and both it and the original class must be subclasses of the same base class. The changeClass method does not modify the security for an object, even if the object's current security is derived from the default security for its source class. For the object's user-defined properties, the following rules apply:

When the class of a document object is changed, the default document lifecycle policy of the new class will only be applied to the document object's DocumentLifecyclePolicy property if both of the following scenarios occur:

Parameters:
className - A String specifying the symbolic name, ClassNames constant, ID, or GUIDConstants constant of the class to which this object is to be changed.
Throws:
E_NULL_OR_INVALID_PARAM_VALUE - if className is null or has a length of zero.

move

void move(Folder targetFolder)
Moves this folder and all of its subfolders and contents from its current parent folder to the target parent folder specified.

Note: You cannot move the root folder for the object store.

Parameters:
targetFolder - A Folder object for the intended parent folder for this instance. The target folder must already exist.
Throws:
EngineRuntimeException - Thrown if the target folder is this instance or one of its subfolders.

lock

void lock(int timeout,
          java.lang.String owner)
Sets a new lock or updates an existing lock on the object. Calling this method has no effect in preventing others from updating a locked object (with the exception that others cannot re-lock the locked object). This lock mechanism is used for custom purposes only and has no bearing on the actual ability to update an object.

To successfully execute this method, the current user must have permission to modify this object's properties. For example, locking a Document object requires AccessLevel.WRITE_DOCUMENT.

If the call succeeds:

To update an existing lock, the objects needs to be in the locked state and the current user needs to match the user of the lock. Note that the user is the logged in user, not the owner string. If the call succeeds, then only the LockTimeout property is updated with the timeout value. The owner parameter in this case is ignored. (See the updateLock() method instead.)

Parameters:
timeout - An integer that represents the number of seconds after which the lock will expire. The range of values is 0 to 2147483647 (Integer.MAX_VALUE) seconds.
owner - A String representing the user name to be assigned as the owner of the lock on this object. Defaults to the short principal name of the requesting user. The value is strictly advisory and is not validated against user or group names known to the Content Engine. The value can be used by applications such as WebDAV to identify the user who has locked the object.
Throws:
E_OBJECT_LOCKED - If the object is already locked and the current user does not match the user of the lock.
E_OBJECT_NOT_LOCKED - If the user tries to update an existing lock but the object is not locked (absence of a LockToken).

createSubFolder

Folder createSubFolder(java.lang.String name)
Creates a directly-contained subfolder of this folder.

Parameters:
name - A String containing the name to assign to the new child folder.
Returns:
A Folder object for the new child folder.

updateLock

void updateLock(long timeout)
Adjusts the timeout period of the lock on this object.

This method updates the object's DateLastModified property to the current time and its LockTimeout property to the timeout value. The net effect of this may extend or shorten the original lock's expiration time. Only the user who locked the object can successfully call this method; for any other user, an exception is thrown. There is no limit to the number of times you can call this method.

Parameters:
timeout - The changed timeout value, in seconds, for this object's lock. The range of values is 0 to 2147483647 (Integer.MAX_VALUE) seconds.

file

ReferentialContainmentRelationship file(IndependentlyPersistableObject containee,
                                        AutoUniqueName autoUniqueName,
                                        java.lang.String containmentName,
                                        DefineSecurityParentage defineSecurityParentage)
Files an instance of a Containable subclass to this folder. Depending on the Containable subclass filed, a ReferentialContainmentRelationship object (for CustomObject and Folder objects) or a DynamicReferentialContainmentRelationship (for Document objects) is created to reference this folder and the containee (instance filed).

Parameters:
containee - An IndependentlyPersistableObject object for the Containable subclass instance to be filed.
autoUniqueName - An AutoUniqueName object indicating whether to detect and resolve naming collisions of containment names.
containmentName - A String containing the containment name to assign to the new object. By default, this is the file name of the object. The following characters are not allowed:
    \  /  :  ∗  ?  "  <  >  | 
defineSecurityParentage - A DefineSecurityParentage object indicating whether the containing folder is to be used as a security parent. If so, the SecurityFolder property of the object being added is automatically set to this folder.
Returns:
A ReferentialContainmentRelationship object where this folder is the tail and the object filed (containee) is the head.
See Also:
unfile

applySecurityTemplate

void applySecurityTemplate(Id applyStateId)
Applies a security policy template to the given object. The specified value for the applyStateId parameter must match the value of the ApplyStateID property of one of the templates in the security policy for the object. For a versioning security template, the apply state ID can be one of the following:
  • VersionStatusId.IN_PROCESS
  • VersionStatusId.RELEASED
  • VersionStatusId.RESERVATION
  • VersionStatusId.SUPERSEDED
For an application security template, the apply state ID is defined by your application.

Parameters:
applyStateId - An Id object representing the unique identifier of the security template to apply.

unlock

void unlock()
Explicitly removes the lock from this object. Only the user who locked the object may remove the lock. If the current user is not the user of the lock, the current user can still remove the lock provided tht user has AccessRight.WRITE_ACL permission on the object. An exception is thrown if the above conditions are not met. Upon successful execution of this method, the values for the object's LockOwner, LockToken, and LockTimeout properties are removed (set to null). If you do not call unlock to explicitly remove the lock, the lock is implicitly removed when the lock's timeout value expires.

Throws:
E_OBJECT_NOT_LOCKED - If the object is not locked.

unfile

ReferentialContainmentRelationship unfile(java.lang.String containmentName)
Unfile the object using a path specification.



© Copyright IBM Corporation 2006, 2009. All rights reserved.