Package com.polarion.alm.projects

Interface IProjectService

public interface IProjectService

The root service to manage projects. This component provides ways to create, modify and delete projects.

In some environments, project creation and deletion might not be supported, because they are controlled by other means. If so, the getLifecycleManager() will return null.

Author:

dobisekm

Method Summary

Modifier and Type	Method	Description
int	countProjects(String query)
int	countUsers(String query)
IUser	createUser(String loginName)	Creates the new instance of the IUser temporary object.
IUserGroup	createUserGroup(String id, String name)	Creates a new instance of the IUserGroup temporary object.
void	deleteUser(IUser user)	Deletes the given user instance.
IUser	getCurrentUser()	Consults ISecurityService to identify the User ID executing this code and transforms the ID into the (unresolved) IUser object.
IDataService	getDataService()	The base data service instance used by the IProjectService.
IGroupEntity	getGroupEntityAtLocation(ILocation loc)	Returns the IGroupEntity (a IProject or IProjectGroup), that exactly matches the given location.
IGroupEntity	getGroupEntityForContextId(IContextId contextId)	Returns the IGroupEntity (a IProject or IProjectGroup) representing the given context.
IGroupEntity	getGroupEntityOwningLocation(ILocation loc)	Similar to getGroupEntityAtLocation(ILocation), but returns the entity even if the given location lies inside that entity.
ILdapUserGroupSynchronization	getLdapUserGroupSynchronization()
ILdapUsersSynchronization	getLdapUsersSynchronization()
ILDAPUserSynchronization	getLDAPUserSynchronization()	Deprecated. Since 3.20.1 use getLdapUsersSynchronization().
IProjectLifecycleManager	getLifecycleManager()
IProject	getProject(String projectId)
IProject	getProjectAtLocation(ILocation loc)	Returns the project located at the given location.
IProject	getProjectForContextId(IContextId contextId)	Returns the IProject representing the given context or null if the context represents a project Group.
IProjectGroup	getProjectGroupAtLocation(ILocation loc)	Returns the project Group located at the given location.
IProjectGroup	getProjectGroupForContextId(IContextId contextId)	Returns the IProjectGroup representing the given context or null if the context represents a project.
IProjectGroup	getProjectGroupForPath(String projectGroupPath)	Returns the IProjectGroup, that contains the location.
IProjectGroup	getProjectGroupOwningLocation(ILocation loc)	Returns the project Group that contains the given location.
IProject	getProjectOwningLocation(ILocation loc)	Returns the project located at or above a given location.
IPObjectList<IUser>	getProjectUsers(IProject project)
IProjectGroup	getRootProjectGroup()
IUser	getUser(String userId)	Returns the user with the given ID.
String	getUserAvatarURL(String userId)	Returns a user avatar image URL.
IUserGroup	getUserGroup(String userGroupId)	Returns the User Group with the given ID.
IPObjectList<IUserGroup>	getUserGroups()
IPObjectList<IUser>	getUsers()
IPObjectList<IUser>	getUsersNotInProject(IProject project)
String	hasBeenModifiedSince(String revision)	Useful for the invalidation of some project caches.
ILdapSyncBuilder	ldap()	Constructs the LDAP synchronization flow builder. Polarion supports multiple LDAP configurations, defined in the authentication.xml file.
ILogin	login()	Create a login flow builder
Subject	login(String userId, String credentials, String source)	Deprecated. Since 3.21.1 please use login() and ILogin.IUsingAuthenticator.with(com.polarion.platform.security.login.IPassword)
Subject	loginWithToken(String token, String source)	Deprecated. Since 3.21.1 please use login() and ILogin.IUsingAuthenticator.with(com.polarion.platform.security.login.IToken)
IPObjectList<IProject>	searchProjects(String query)
IPObjectList<IProject>	searchProjects(String query, String sort)
IPObjectList<IUser>	searchProjectUsers(IProject project, String query, String sort)
IPObjectList<IUserGroup>	searchUserGroups(String query, String sort, int resultLimit)	Searches for User Groups matching the query.
IPObjectList<IUser>	searchUsers(String query)
IPObjectList<IUser>	searchUsers(String query, String sort)

Method Details

getDataService

IDataService getDataService()

The base data service instance used by the IProjectService.

Returns:

the IDataService used by this service.

createUser

IUser createUser(String loginName)

Creates the new instance of the IUser temporary object. The instance is not persistent until the save method is invoked.

Parameters:

loginName -

Returns:

the new IUser instance.

deleteUser

void deleteUser(IUser user)

Deletes the given user instance.

Parameters:

user -

getUser

@NotNull
IUser getUser(@NotNull
 String userId)

Returns the user with the given ID.

Returns:

the unresolved IPObject with the given ID. The operation is performed using only the IDs, so there is no guarantee that such a user actually exists and will be resolvable. Never returns null.

getUserAvatarURL

String getUserAvatarURL(String userId)

Returns a user avatar image URL. Can be the user's uploaded image, a reference to an external image or the default image. The URL may be absolute, or relative to the portal's base URL. The user can be unresolvable, or not yet persisted. The user ID can also be null.

Parameters:

userId - ID of a user or null

Returns:

avatar URL, never null

Since:

3.6.0

getCurrentUser

IUser getCurrentUser()

Consults ISecurityService to identify the User ID executing this code and transforms the ID into the (unresolved) IUser object.

Note: the resulting IUser is not guaranteed to be resolvable.

Returns:

the current user or null if there is no subject executing this code.

getUsers

@NotNull
IPObjectList<IUser> getUsers()

Returns:

a list of everyone registered in the system IUser

getProjectUsers

@NotNull
IPObjectList<IUser> getProjectUsers(IProject project)

Parameters:

project -

Returns:

a list of project usersIUser

getUsersNotInProject

@NotNull
IPObjectList<IUser> getUsersNotInProject(IProject project)

Parameters:

project -

Returns:

a list of users that do not belong to a specified project IUser In other words it returns a list of all users except the users returned by getProjectUsers().

searchProjectUsers

@NotNull
IPObjectList<IUser> searchProjectUsers(IProject project,
 String query,
 String sort)

Returns:

a list of users found in the project IUser. It is significantly slower than getProjectUsers, so use it only when needed.

searchUsers

@NotNull
IPObjectList<IUser> searchUsers(String query)

Returns:

a list of all users found in the system. IUser

searchUsers

@NotNull
IPObjectList<IUser> searchUsers(String query,
 String sort)

Returns:

list of all users found in the system IUser

countUsers

int countUsers(String query)

Returns:

the number of users matching the given query. This should be faster than searchUsers(query).size()

See Also:

• searchUsers(String)

getRootProjectGroup

IProjectGroup getRootProjectGroup()

searchProjects

@NotNull
IPObjectList<IProject> searchProjects(String query)

searchProjects

@NotNull
IPObjectList<IProject> searchProjects(String query,
 String sort)

countProjects

int countProjects(String query)

Returns:

the number of projects matching the given query. This should be faster than searchProjects(query).size()

See Also:

• searchProjects(String)

getLifecycleManager

IProjectLifecycleManager getLifecycleManager()

Returns:

the project life cycle manager or null if life cycle management is not supported in this environment.

getProject

IProject getProject(String projectId)

Returns:

the unresolved IPObject with the given ID. The operation is performed with just the IDs, so there is no guarantee that such a project really exists and will be resolvable. Never returns null.

Throws:

IllegalArgumentException - if projectId is null

getGroupEntityAtLocation

IGroupEntity getGroupEntityAtLocation(ILocation loc)

Returns the IGroupEntity (a IProject or IProjectGroup), that exactly matches the given location. Returns null if the location does not match any Group entity (even if it lies INSIDE of the entity).

Parameters:

loc - The Location, might be null (= root Group).

See Also:

• getGroupEntityOwningLocation(ILocation)
• getProjectAtLocation(ILocation)
• getProjectGroupAtLocation(ILocation)

getGroupEntityOwningLocation

IGroupEntity getGroupEntityOwningLocation(ILocation loc)

Similar to getGroupEntityAtLocation(ILocation), but returns the entity even if the given location lies inside that entity.

Parameters:

loc - the Location, might be null (= root Group).

Returns:

the Group entity owning the location. Never returns null, since even a completely nonexistent location is still owned by the ROOT Group.

See Also:

• getGroupEntityAtLocation(ILocation)
• getProjectOwningLocation(ILocation)
• getProjectGroupOwningLocation(ILocation)

getGroupEntityForContextId

IGroupEntity getGroupEntityForContextId(IContextId contextId)

Returns the IGroupEntity (a IProject or IProjectGroup) representing the given context.

Parameters:

contextId -

Returns:

IGroupEntity (a IProject or IProjectGroup), never returns null.

Throws:

IllegalArgumentException - if the contextId is null or no such context exists.

See Also:

• getProjectForContextId(IContextId)
• getProjectGroupForContextId(IContextId)

getProjectAtLocation

IProject getProjectAtLocation(ILocation loc)

Returns the project located at the given location. Returns null if the location does not map to a project or if it maps to IProjectGroup.

Parameters:

loc - the Location. Might be null (= root group).

Returns:

the project or null

See Also:

• getProjectOwningLocation(ILocation)
• getGroupEntityAtLocation(ILocation)
• getProjectGroupAtLocation(ILocation)

getProjectOwningLocation

IProject getProjectOwningLocation(ILocation loc)

Returns the project located at or above a given location. Returns null if the location lies inside (inclusive) of a project.

Parameters:

loc - the Location, might be null (= root Group).

Returns:

the project or null

See Also:

• getProjectAtLocation(ILocation)
• getGroupEntityAtLocation(ILocation)
• getProjectGroupAtLocation(ILocation)

getProjectForContextId

@Nullable
IProject getProjectForContextId(IContextId contextId)

Returns the IProject representing the given context or null if the context represents a project Group.

Parameters:

contextId -

Returns:

IProject or null.

Throws:

IllegalArgumentException - if the contextId is null or no such context exists.

See Also:

• getGroupEntityForContextId(IContextId)
• getProjectGroupForContextId(IContextId)

getProjectGroupAtLocation

IProjectGroup getProjectGroupAtLocation(ILocation loc)

Returns the project Group located at the given location. Returns null if the location does not map to a project group. (For example, if it maps to a project).

Parameters:

loc - the Location, might be null (= root group).

Returns:

the project Group or null

See Also:

• getProjectGroupOwningLocation(ILocation)
• getGroupEntityAtLocation(ILocation)
• getProjectAtLocation(ILocation)

getProjectGroupOwningLocation

IProjectGroup getProjectGroupOwningLocation(ILocation loc)

Returns the project Group that contains the given location. Even if the location lies inside the project in this Group, the Group is still returned.

Parameters:

loc - the Location, might be null (= root Group).

Returns:

the project Group. Never returns null, since all locations are owned by the Root Group.

See Also:

• getProjectGroupAtLocation(ILocation)
• getGroupEntityOwningLocation(ILocation)
• getProjectOwningLocation(ILocation)

getProjectGroupForContextId

IProjectGroup getProjectGroupForContextId(IContextId contextId)

Returns the IProjectGroup representing the given context or null if the context represents a project.

Parameters:

contextId -

Returns:

IProjectGroup or null.

Throws:

IllegalArgumentException - if the contextId is null or no such context exists.

See Also:

• getGroupEntityForContextId(IContextId)
• getProjectForContextId(IContextId)

getProjectGroupForPath

@NotNull
IProjectGroup getProjectGroupForPath(@Nullable
 String projectGroupPath)

Returns the IProjectGroup, that contains the location. created from the given path. Even if the location lies inside the project in this Group, the Group is still returned.

Parameters:

path - the Group path to create the appropriate location.

Returns:

the project Group. Never returns null, since all locations are owned by the Root Group.

Since:

3.10.1

See Also:

• getProjectGroupAtLocation(ILocation)
• getGroupEntityOwningLocation(ILocation)
• getProjectOwningLocation(ILocation)

getLDAPUserSynchronization

@Deprecated
@NotNull
ILDAPUserSynchronization getLDAPUserSynchronization()

Deprecated.

Since 3.20.1 use getLdapUsersSynchronization().

getLdapUsersSynchronization

@NotNull
ILdapUsersSynchronization getLdapUsersSynchronization()

Since:

3.20.1

getLdapUserGroupSynchronization

@NotNull
ILdapUserGroupSynchronization getLdapUserGroupSynchronization()

Since:

3.20.1

ldap

@NotNull
ILdapSyncBuilder ldap()

Constructs the LDAP synchronization flow builder.
Polarion supports multiple LDAP configurations, defined in the authentication.xml file. These configurations can be used for user and group synchronizations.
For more information about the authentication.xml file, see the "Authentication guide" section in Polarion's Help.

This method must be used instead of getLDAPUserSynchronization(), getLdapUsersSynchronization(), getLdapUserGroupSynchronization(), if Polarion is configured to work with multiple LDAP configurations.

Returns:

synchronization process flow builder

Since:

3.21.1

login

@Deprecated
Subject login(String userId,
 String credentials,
 String source)
       throws AuthenticationFailedException,
LoginDeniedException

Deprecated.

Since 3.21.1 please use login() and ILogin.IUsingAuthenticator.with(com.polarion.platform.security.login.IPassword)

A user object with the given ID must exist for a successful login. It can however be auto-created as a part of the call of this method. (If auto-creation is configured appropriately). Must NOT be called within a transaction.

Requires only one configured authentication provider. If more than one is configured, use the method with authenticatorId parameter

Parameters:

userId -

credentials -

source -

Returns:

authenticated subject (not null)

Throws:

IllegalStateException - if Polarion is configured to use more than one authentication provider.

AuthenticationFailedException

LoginDeniedException

loginWithToken

@Deprecated
@NotNull
Subject loginWithToken(@NotNull
 String token,
 @NotNull
 String source)
                throws AuthenticationFailedException

Deprecated.

Since 3.21.1 please use login() and ILogin.IUsingAuthenticator.with(com.polarion.platform.security.login.IToken)

Logs in the user with SASL security

To have Teamcenter Security Services (TCSS) log in with a token, you need to first use the following method to create a Base64 encoded token TcssToken.create(String, String).

For SAML, a token should be passed as is. For SPNEGO/Kerberos or OAuth2 it should be encoded using the Base64

Requires only one configured authentication provider. If more than one is configured, use the method with authenticatorId parameter

Parameters:

token - the token used for validation. Cannot be null. The token must be encoded using the Base64 encoding scheme.

source - the login source (e.g. "portal/IP" or "system") - Used only for logging.

Returns:

Authenticated subject (not null).

Throws:

AuthenticationFailedException - If the given token is not valid or if the user does not exist in the system and auto-creation is not enabled. It also throws an exception if a user does not have sufficient permissions to log in.

IllegalArgumentException - If the mechanism, token or source are null.

IllegalStateException - if Polarion is configured to use more than one authentication provider.

Since:

3.17.0

login

@NotNull
ILogin login()

Create a login flow builder

Returns:

new login flow builder

Since:

3.21.1

hasBeenModifiedSince

String hasBeenModifiedSince(String revision)

Useful for the invalidation of some project caches. Inspired by the if-modified-since feature of the http protocol.

Parameters:

revision - the last revision seen by the client. (The revision of its cached data), or null if not known.

Returns:

null if data in the related projects has not been changed, or a new revision of project related data signals that the client has to invalidate its caches.

Since:

3.7.3

getUserGroup

@NotNull
IUserGroup getUserGroup(@NotNull
 String userGroupId)

Returns the User Group with the given ID.

Returns:

the unresolved IPObject with the given ID. The operation is performed using only the IDs, so there is no guarantee that such a User Group exists and will be resolvable. Never returns null.

Since:

3.19.3

getUserGroups

@NotNull
IPObjectList<IUserGroup> getUserGroups()

Returns:

a list of all User Groups in the system.

Since:

3.19.3

searchUserGroups

@NotNull
IPObjectList<IUserGroup> searchUserGroups(@Nullable
 String query,
 @Nullable
 String sort,
 int resultLimit)

Searches for User Groups matching the query.

Parameters:

query -

sort -

resultLimit - The maximum size of the returned list. A negative number means that there is no limit.

Returns:

a IPObjectList containing the result of the query.

Since:

3.19.3

See Also:

• IDataService.searchInstances(IPrototype, String, String, int)

createUserGroup

@NotNull
IUserGroup createUserGroup(@NotNull
 String id,
 @NotNull
 String name)

Creates a new instance of the IUserGroup temporary object. The instance is not persistent until the save method is invoked.

Returns:

a new IUserGroup instance.

Since:

3.19.3