com.ibm.workplace.wcm.api
Interface Project

All Superinterfaces:

Document, Editable, EditableItem, Item, Localized, WCMApiObject

public interface Project
extends Editable

This class represents Project object

Since:

7.0

Nested Class Summary

static class	Project.ApprovalMode The list of valid project approval modes
static class	Project.CommentMode The list of valid project comment modes
static class	Project.PublishOptions The list of valid project publish options

Method Summary

void	addApprovers(java.lang.String... approverNames) Add the given names as approvers on this object.
void	approve() Approves the project.
void	approve(java.lang.String comment) Approves the current project with a valid comment.
boolean	canPublish() Checks if the project is in a State that allows publishing.
void	clearApprovers() A convenient method to remove all approvers from the object.
void	clearWorkflowActionsForState(ProjectStateSelectors.State state) A convenient method to clear all WorkflowActions currently associated with the given State.
void	decline() Declines this project.
void	decline(java.lang.String comment) Declines the current project with a valid comment.
Project.ApprovalMode	getApprovalMode() Get the ApprovalMode set on this object.
Project.CommentMode	getCommentMode() Gets the CommentMode of this project.
java.lang.String[]	getCurrentApprovers() Returns a string array of members who have Approver access to this object.
long	getItemCount() Obtain the number of items on this project
DocumentIdIterator	getItemIds() Get items on this project.
DocumentIdIterator	getItemIdsByWorkflowStatus(WorkflowSelectors.Status workflowStatus) Obtained items with the specified workflow status on this project
ResultIterator<Document>	getItems() Get items on this project.
ResultIterator<Document>	getItems(boolean asReference, boolean loadElements) Get items on this project.
ResultIterator<Document>	getItemsByWorkflowStatus(WorkflowSelectors.Status workflowStatus) Obtained items with the specified workflow status on this project.
ResultIterator<Document>	getItemsByWorkflowStatus(WorkflowSelectors.Status workflowStatus, boolean asReference, boolean loadElements) Obtained items with the specified workflow status on this project
java.util.Locale	getLocale() Gets the Locale of this project.
java.lang.String[]	getOutstandingApprovers() Returns a string array of members who have Approver access to this Project object but have yet to approve it.
long	getPublishDate() Gets the date used by the 'Date' publish option
Project.PublishOptions	getPublishOption() Gets the current project publish option
ProjectStateSelectors.State	getState() Gets the State of this project.
DocumentId[]	getWorkflowActionsForState(ProjectStateSelectors.State state) Get the list of WorkflowActions associated with the given project State.
boolean	hasApproverAccess() Checks if the user of the Workspace associated with the current project has Approver access to this project.
boolean	hasApproverAccess(UserProfile user) Checks if the UserProfile has Approver access to this project.
void	publish() Publish this project.
void	removeApprovers(java.lang.String... approvers) Removes the given approvers from the approver list for this object.
void	setApprovalMode(Project.ApprovalMode approvalMode) Set the ApprovalMode on this object.
void	setCommentMode(Project.CommentMode commentMode) Sets the CommentMode for this project.
void	setLocale(java.util.Locale locale) Sets the Locale of this project object.
void	setPublishDate(long publishDate) Sets the date used by the 'Date' publish option
void	setPublishOption(Project.PublishOptions publishOption) Sets the publish option on this project
void	setWorkflowActionsForState(ProjectStateSelectors.State state, DocumentId... workflowActionDocumentIds) Set the given WorkflowActions for the specified State of this Project.
void	submitForReview() Submits this project for review.
void	withdrawApproval() Withdraws the approval of the current user from the project.
void	withdrawFromReview() Withdraws this project from the ProjectStateSelectors.State.REVIEW state.

Methods inherited from interface com.ibm.workplace.wcm.api.Editable

addAuthors, addContributorAccessMembers, addDeleteAccessMembers, addEditAccessMembers, addEditorAccessMembers, addHistoryLogEntry, addLiveAccessMembers, addManagerAccessMembers, addMembersForAccess, addOwners, addReadAccessMembers, addUserAccessMembers, isChanged, removeAuthors, removeContributorAccessMembers, removeDeleteAccessMembers, removeEditAccessMembers, removeEditorAccessMembers, removeLiveAccessMembers, removeManagerAccessMembers, removeMembersForAccess, removeOwners, removeReadAccessMembers, removeUserAccessMembers, setContributorAccessInheritance, setDescriptionTextProviderKey, setDescriptionTextProviderName, setEditorAccessInheritance, setInheritance, setManagerAccessInheritance, setPropagation, setTitleTextProviderKey, setTitleTextProviderName, setUserAccessInheritance

Methods inherited from interface com.ibm.workplace.wcm.api.Document

getAuthors, getContributorAccessMembers, getCreator, getDeleteAccessMembers, getDescription, getDescriptionTextProviderKey, getDescriptionTextProviderName, getEditAccessMembers, getEditorAccessMembers, getHistoryLog, getId, getInheritedContributorAccessMembers, getInheritedEditorAccessMembers, getInheritedManagerAccessMembers, getInheritedUserAccessMembers, getLastModifier, getLiveAccessMembers, getManagerAccessMembers, getMembersForAccess, getMembersForInheritedAccess, getOwnerLibrary, getOwners, getProject, getReadAccessMembers, getSourceWorkspace, getTitle, getTitleTextProviderKey, getTitleTextProviderName, getUserAccessMembers, getVersionCatalog, getVersionStrategy, hasDeleteAccess, hasDeleteAccess, hasEditAccess, hasEditAccess, hasLiveAccess, hasLiveAccess, hasProject, hasReadAccess, hasReadAccess, isContributorAccessInherited, isEditorAccessInherited, isInherited, isManagerAccessInherited, isNew, isPropagated, isUserAccessInherited, isWorkflowed

Methods inherited from interface com.ibm.workplace.wcm.api.Item

getCreationDate, getDescription, getIdentity, getModifiedDate, getName, getTitle

Methods inherited from interface com.ibm.portal.Localized

getLocales

Methods inherited from interface com.ibm.workplace.wcm.api.EditableItem

setDescription, setName, setTitle

Method Detail

canPublish

boolean canPublish()

Checks if the project is in a State that allows publishing.

Returns:

true if the project is in a valid state to publish , false otherwise.

Since:

8.0

publish

void publish()
             throws ProjectException

Publish this project. Before calling this method, all Documents on this project have to be moved into pending published status by EditableWorkflowDocument.nextWorkflowStage().
Project is allowed to publish if:

• Project is not managed by syndication. Syndicated projects should be published on the original Syndicator server
• Project is in ProjectStateSelectors.State#PENDING or ProjectStateSelectors.State#PUBLISHED_FAILED state
• Project in Active State is allowed to publish if
• publish option is not automatic
• there is no review state
• the project has no items

Note that if a publish fails this method will still complete and the project will be in ProjectStateSelectors.State#PUBLISHED_FAILED state.

Throws:

ProjectException - Generic issue with publishing the project

ProjectInvalidStateException - If the project is not in a valid state to publish. Check if valid by calling canPublish()

getItems

ResultIterator<Document> getItems()

Get items on this project.

The returned Document(s) are cloned and elements pre-loaded

Returns:

Obtained Document(s) on this project

getItems

ResultIterator<Document> getItems(boolean asReference,
                                  boolean loadElements)

Get items on this project.

Parameters:

asReference - when true this will not clone the internal Document.

loadElements - when true any elements on the Document will be auto-loaded. Non-loaded elements are still accessible, but its faster to auto-load (the default) if the elements will be used.

Returns:

Obtained Document(s) on this project

getItemIds

DocumentIdIterator getItemIds()

Get items on this project.

Returns:

Obtained DocumentId(s) on this project

getItemsByWorkflowStatus

ResultIterator<Document> getItemsByWorkflowStatus(WorkflowSelectors.Status workflowStatus)
                                                  throws QueryServiceException

Obtained items with the specified workflow status on this project.

An item being marked for deletion has DRAFT as its workflow status, and DELETED as its pending state. Therefore it will be included as a result of this method for only DRAFT status.

The returned Document(s) are cloned and elements pre-loaded

Parameters:

workflowStatus - Workflow status defined by com.ibm.workplace.wcm.api.query.WorkflowSelectors.Status.

Returns:

All documents with the specified status

Throws:

QueryServiceException - if exception occurs during internal querying process.

getItemsByWorkflowStatus

ResultIterator<Document> getItemsByWorkflowStatus(WorkflowSelectors.Status workflowStatus,
                                                  boolean asReference,
                                                  boolean loadElements)
                                                  throws QueryServiceException

Obtained items with the specified workflow status on this project

An item being marked for deletion has DRAFT as its workflow status, and DELETED as its pending state. Therefore it will be included as a result of this method for only DRAFT status.

Parameters:

workflowStatus - Workflow status defined by com.ibm.workplace.wcm.api.query.WorkflowSelectors.Status.

asReference - when true this will not clone the internal Document.

loadElements - when true any elements on the Document will be auto-loaded. Non-loaded elements are still accessible, but its faster to auto-load (the default) if the elements will be used.

Returns:

All documents with the specified status

Throws:

QueryServiceException - if exception occurs during internal querying process.

getItemIdsByWorkflowStatus

DocumentIdIterator getItemIdsByWorkflowStatus(WorkflowSelectors.Status workflowStatus)
                                              throws QueryServiceException

Obtained items with the specified workflow status on this project

An item being marked for deletion has DRAFT as its workflow status, and DELETED as its pending state. Therefore it will be included as a result of this method for only DRAFT status.

Parameters:

workflowStatus - Workflow status defined by com.ibm.workplace.wcm.api.query.WorkflowSelectors.Status.

Returns:

All documents with the specified status

Throws:

QueryServiceException - if exception occurs during internal querying process.

getItemCount

long getItemCount()

Obtain the number of items on this project

Returns:

The number of items on this project

getPublishOption

Project.PublishOptions getPublishOption()

Gets the current project publish option

Returns:

the current project publish option

setPublishOption

void setPublishOption(Project.PublishOptions publishOption)
                      throws ProjectException

Sets the publish option on this project

Parameters:

publishOption - the publish option to set

Throws:

ProjectException - if the specified publish option can not be set.

getPublishDate

long getPublishDate()

Gets the date used by the 'Date' publish option

Returns:

the date used by the 'Date' publish option

setPublishDate

void setPublishDate(long publishDate)
                    throws ProjectException

Sets the date used by the 'Date' publish option

Parameters:

publishDate - the date used by the 'Date' publish option

Throws:

ProjectException - if the specified publish date can not be set.

getLocale

java.util.Locale getLocale()

Gets the Locale of this project. The meta data of this project should be populated with values in the given Locale.

Returns:

the Locale of the project.

Since:

8.0

setLocale

void setLocale(java.util.Locale locale)

Sets the Locale of this project object. The Locale specified should be representative of the meta data set on this project.

Parameters:

locale - the Locale to set on this project

Since:

8.0

getState

ProjectStateSelectors.State getState()

Gets the State of this project.

Returns:

State of the project

Since:

8.0

setWorkflowActionsForState

void setWorkflowActionsForState(ProjectStateSelectors.State state,
                                DocumentId... workflowActionDocumentIds)

Set the given WorkflowActions for the specified State of this Project. This list will override any existing actions associated with the defined State. The given WorkflowActions will be added and executed in the defined order. Duplicate WorkflowActions will be ignored.

Parameters:

state - the non-null project State to set the WorkflowAction on. All project States except ACTIVE support WorkflowAction.

workflowActionDocumentIds - a non-null, non-empty list of DocumentId whose type must be assignable to that of a WorkflowAction.

Throws:

java.lang.IllegalArgumentException - if the specified state is null or does not support WorkflowAction. or the DocumentId array is null or empty, or if no WorkflowAction object exists for a given DocumentId.

java.lang.IllegalStateException - if the project's current State is not ACTIVE.

clearWorkflowActionsForState

void clearWorkflowActionsForState(ProjectStateSelectors.State state)

A convenient method to clear all WorkflowActions currently associated with the given State.

Parameters:

state - the project State to clear all the associated WorkflowAction for.

Throws:

java.lang.IllegalArgumentException - if the specified state is null.

java.lang.IllegalStateException - if the project's current State is not ACTIVE.

getWorkflowActionsForState

DocumentId[] getWorkflowActionsForState(ProjectStateSelectors.State state)

Get the list of WorkflowActions associated with the given project State. If the given project State has no WorkflowAction associated with it then an empty array will be returned.

Parameters:

state - the non-null project state to query associated WorkflowActions for.

Returns:

the array of WorkflowActions, defined on the given project State, or an empty array is there is none.

addApprovers

void addApprovers(java.lang.String... approverNames)

Add the given names as approvers on this object. A name is added only if it can be converted to a valid user or group.

Parameters:

approverNames - the names of users and/or groups to be set as approvers on this object. These names are either the common names or distinguished names, depending on the setting on the Workspace. See Workspace.isDistinguishedNamesUsed().

Throws:

java.lang.IllegalStateException - if the project's current state is not ACTIVE.

Since:

8.0

removeApprovers

void removeApprovers(java.lang.String... approvers)

Removes the given approvers from the approver list for this object.

An approver is only removed if it can be converted to a valid member and is already in the list of approvers for this object.

Note: Each approver is either a user's common name or distinguished name depending on the setting on the Workspace. See Workspace.isDistinguishedNamesUsed().

Parameters:

approvers - the approvers names to remove from this object.

Throws:

java.lang.IllegalStateException - if the project's current state is not ACTIVE.

Since:

8.0

clearApprovers

void clearApprovers()

A convenient method to remove all approvers from the object. This is equivalent to retrieving all approvers then perform removeApprovers(String...)

Throws:

java.lang.IllegalStateException - if the project's current state is not ACTIVE.

Since:

8.0

getCurrentApprovers

java.lang.String[] getCurrentApprovers()
                                       throws PropertyRetrievalException

Returns a string array of members who have Approver access to this object. The strings are either the users' common names or distinguished names, depending on the setting on the Workspace. See Workspace.isDistinguishedNamesUsed().

The resultant array may contain the names of users and groups.

Returns an empty array if this object does not have Approver access specified.

Returns:

a string array of members that have Approver access to this object.

Throws:

PropertyRetrievalException - if this document is not workflowable, or the current stage is not accessible by this user

Since:

8.0

getOutstandingApprovers

java.lang.String[] getOutstandingApprovers()

Returns a string array of members who have Approver access to this Project object but have yet to approve it. The strings are either the users' common name or distinguished name, depending on the setting on the Workspace. See Workspace.isDistinguishedNamesUsed().

The resultant array may contain the names of users and groups.

Returns an empty array if this Project object does not have any outstanding approvers.

Returns:

a string array of members that have Approver access to this project but have yet to approve it.

hasApproverAccess

boolean hasApproverAccess(UserProfile user)
                          throws WorkflowException

Checks if the UserProfile has Approver access to this project.

Parameters:

user - the UserProfile to perform the access check for.

Returns:

true if this user has Approver access, false if not.

Throws:

WorkflowException - if error occurs when accessing repository.

Since:

8.0

hasApproverAccess

boolean hasApproverAccess()
                          throws WorkflowException

Checks if the user of the Workspace associated with the current project has Approver access to this project.

Returns:

true if this user has Approver access, false if not

Throws:

WorkflowException - if error occurs when accessing repository

setCommentMode

void setCommentMode(Project.CommentMode commentMode)

Sets the CommentMode for this project.

Parameters:

commentMode - the CommentMode to be set on this project.

Throws:

java.lang.IllegalStateException - if the project's current state is not ProjectStateSelectors.State.ACTIVE.

java.lang.IllegalArgumentException - if the given CommentMode is null.

Since:

8.0

getCommentMode

Project.CommentMode getCommentMode()

Gets the CommentMode of this project.

Returns:

the project's CommentMode.

Since:

8.0

setApprovalMode

void setApprovalMode(Project.ApprovalMode approvalMode)

Set the ApprovalMode on this object.

Parameters:

approvalMode - the ApprovalMode to be set.

Throws:

java.lang.IllegalArgumentException - if the argument is null.

java.lang.IllegalStateException - if invoked on a Project and the project's current state is not ACTIVE.

Since:

8.0

getApprovalMode

Project.ApprovalMode getApprovalMode()

Get the ApprovalMode set on this object.

Returns:

the object's ApprovalMode

Since:

8.0

submitForReview

void submitForReview()
                     throws AuthorizationException,
                            WorkflowException

Submits this project for review.

Required access level: minimum Editor access to the project.

Precondition: 1. The project needs to be in ProjectStateSelectors.State.ACTIVE. 2. The project must have at least one defined Approver.

Post-condition: Project will be in ProjectStateSelectors.State.REVIEW state.

Throws:

AuthorizationException - if required access level is not met.

java.lang.IllegalStateException - if the project's current state is not ProjectStateSelectors.State.ACTIVE.

WorkflowException - if the project can not be put in ProjectStateSelectors.State.REVIEW state.

Since:

8.0

withdrawFromReview

void withdrawFromReview()
                        throws AuthorizationException,
                               WorkflowException

Withdraws this project from the ProjectStateSelectors.State.REVIEW state. This will put the project back into the ProjectStateSelectors.State.ACTIVE state.

Required access level: minimum Editor access to the project.

Precondition: 1. The project needs to be in ProjectStateSelectors.State.REVIEW.

Post-condition: 1. Project will be in ProjectStateSelectors.State.ACTIVE state. 2. Existing approvals will be cleared.

Throws:

AuthorizationException - if required access level is not met.

java.lang.IllegalStateException - if the project's current state is not ProjectStateSelectors.State.REVIEW.

WorkflowException - if the project can not be put in ProjectStateSelectors.State.ACTIVE state.

Since:

8.0

approve

void approve()
             throws AuthorizationException,
                    WorkflowException

Approves the project.

Required access level: Approver access to the project.

Precondition: 1. The project needs to be in ProjectStateSelectors.State.REVIEW.

Post-condition: 1. If project's ApprovalMode is ApprovalMode.REQUIRE_SINGLE_APPROVAL then the project will be in PENDING state. 2. Else if project's ApprovalMode is ApprovalMode.REQUIRE_ALL_APPROVALS AND user is the last outstanding approver then project will be in PENDING state. 3. Else, project will remain in the current REVIEWstate until the last outstanding approver approves it.

Throws:

AuthorizationException - if required access level is not met.

java.lang.IllegalStateException - if the project's current state is not ProjectStateSelectors.State.REVIEW.

WorkflowException - if the post conditions can not be achieved.

Since:

8.0

approve

void approve(java.lang.String comment)
             throws AuthorizationException,
                    WorkflowException

Approves the current project with a valid comment. A valid comment in this context is any non-null, non-empty string which does not consist of only whitespaces. Once a valid comment is supplied, it will be set regardless of the project's CommentMode.

Note: if no comment is required in approving this project then the no-arg version approve()} should instead be used.

Parameters:

comment - a valid comment to be used for this approval.

Throws:

java.lang.IllegalArgumentException - if the comment is null or empty or consists of only whitespaces.

AuthorizationException - if user does not have Approver access to this project.

java.lang.IllegalStateException - if the project's current state is not ProjectStateSelectors.State.REVIEW.

WorkflowException - if the post conditions for the approval can not be achieved.

Since:

8.0

See Also:

Project#approve()}}

withdrawApproval

void withdrawApproval()
                      throws AuthorizationException,
                             WorkflowException

Withdraws the approval of the current user from the project.

Required access level: Approver access to the project.

Precondition: 1. The project needs to be in ProjectStateSelectors.State.REVIEW.

Post-condition: 1. Project will stay in ProjectStateSelectors.State.REVIEW state. 2. User's approval on the project will be removed from the list of received approvals.

Throws:

AuthorizationException - if required access level is not met

java.lang.IllegalStateException - if the project's current state is not ProjectStateSelectors.State.REVIEW.

WorkflowException - if the post conditions can not be achieved.

Since:

8.0

decline

void decline()
             throws AuthorizationException,
                    WorkflowException

Declines this project.

Required access level: Approver access to the project.

Precondition: 1. The project needs to be in ProjectStateSelectors.State.REVIEW.

Post-condition: 1. Project will be in ProjectStateSelectors.State.ACTIVE state. 2. All existing approvals on the project will be cleared.

Throws:

AuthorizationException - if the required access level is not met.

java.lang.IllegalStateException - if the project's current state is not ProjectStateSelectors.State.REVIEW.

WorkflowException - if the post conditions can not be achieved.

Since:

8.0

decline

void decline(java.lang.String comment)
             throws AuthorizationException,
                    WorkflowException

Declines the current project with a valid comment. A valid comment in this context is any non-null, non-empty string which does not consist of only whitespaces. Once a valid comment is supplied, it will be set regardless of the project's ApprovalMode.

Note: if no comment is required in declining this project then the no-arg version decline()} should instead be used.

Parameters:

comment - the reason for this rejection.

Throws:

java.lang.IllegalArgumentException - if the comment is null or empty or consists of only whitespaces.

AuthorizationException - if user does not have Approver access to this project.

java.lang.IllegalStateException - if the project's current state is not ProjectStateSelectors.State.REVIEW.

WorkflowException - if the post conditions for approval can not be achieved.

Since:

8.0

See Also:

Project#decline()}