com.nomagic.magicdraw.esi

Class EsiUtils

java.lang.Object

com.nomagic.magicdraw.esi.EsiUtils

@OpenApiAll
public class EsiUtils
extends java.lang.Object

API to work with CEDW server. Before working with users and projects there must be established connection to CEDW server. Connection is established with this code:

EsiUtils.getTeamworkService().login(new ServerLoginInfo("localhost", "user", "password", false), false);

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	EsiUtils.ApplyProjectStateResult A structure that is produced by the applyProjectState(Project, Project) and which holds information about the result of the operation
static interface	EsiUtils.EsiBranchInfo Branch information.

Constructor Summary

Constructors

Constructor and Description
EsiUtils()

Method Summary

Modifier and Type	Method and Description
static void	addCommitTags(java.util.List<java.lang.String> tags, ProjectDescriptor descriptor, long version) Add tags for given version.
static IPrimaryProject	addToESI(Project project, java.lang.String esiProjectName) Add project to the ESI server and open it.
static IPrimaryProject	addToESI(Project project, java.lang.String esiProjectName, java.lang.String category, java.lang.String comment, java.util.List<java.lang.String> tags, java.util.Collection<ResolveLocalModuleInfo> resolveInfos) Add project to the ESI server and open it
static EsiUtils.ApplyProjectStateResult	applyProjectState(Project source, Project target) Applies the state of the source project to the target project, or in other words, overwrites the content of the target project with the contents of the source project.
static void	assignProjectToCategory(ProjectDescriptor project, java.lang.String... categories) Adds or remove project to/from categories.
static void	commitProject(Project project, java.lang.String comment, java.util.Collection<Element> unlockElements, java.util.Collection<ModuleUsage> unlockModules, boolean unlockDecomposition, java.util.List<java.lang.String> tags) Commit project.
static Project	convertToLocal(Project project, java.io.File file) Convert given project to local, save and reopen it.
static void	createBranch(ProjectDescriptor descriptor, long version, java.lang.String branchName, java.lang.String branchDescription) Create new branch for given project.
static void	createCategory(java.lang.String name, java.lang.String description) Create projects category in the server.
static Project	createProject(java.lang.String name, java.lang.String category) Create ESI project.
static void	deleteBranch(ProjectDescriptor descriptor, java.lang.String branchName) Delete project branch.
static void	deleteCategory(java.lang.String name) Delete category with given name.
static void	deleteProject(ProjectDescriptor project) Delete project from repository.
static IAttachedProject	exportEsiModule(Project project, java.util.Collection<Package> packages, java.lang.String description, java.lang.String moduleName) Exports module.
static java.util.List<com.nomagic.esi.api.info.TagInfo>	getAllCommitTagsInfo(ProjectDescriptor descriptor) Get all tags for project.
static java.util.Collection<EsiUtils.EsiBranchInfo>	getBranches(ProjectDescriptor descriptor) Get all branches for given project.
static java.util.UUID	getBranchID(org.eclipse.emf.common.util.URI locationURI) Gets project branch ID.
static java.util.Set<com.nomagic.teamwork.common.projects.CategoryInfo>	getCategories()
static java.util.Map<java.lang.String,java.util.List<ProjectDescriptor>>	getCategoriesToProjects() Get categories for projects.
static java.lang.String	getCategoryID(java.lang.String resourceID) Gets category ID for specified twc project resource ID.
static java.util.List<java.lang.String>	getCommitTags(ProjectDescriptor descriptor, long version) Get tags names for project version.
static java.util.List<com.nomagic.esi.api.info.TagInfo>	getCommitTagsInfo(ProjectDescriptor descriptor, long version) Get tags for project version.
static EsiUtils.EsiBranchInfo	getCurrentBranch(IProject project) Gets branch information for the given TWC project part.
static ProjectDescriptor	getDescriptorByBranchID(ProjectDescriptor project, java.util.UUID branchID) Get project descriptor for given branch.
static ProjectDescriptor	getDescriptorForBranch(ProjectDescriptor project, java.lang.String branchName) Get project descriptor for given branch.
static ProjectDescriptor	getDescriptorForVersion(ProjectDescriptor projectDescriptor, IVersionDescriptor versionDescriptor) Get descriptor for specific version.
static long	getLastVersion(ProjectDescriptor descriptor) Get last project version number.
static ILockProjectService	getLockService(Project project) Provides api to check, request and release locks on various project data.
static java.lang.String	getLoggedUserName() Returns the currently logged ESI user name.
static java.util.Set<java.lang.String>	getLoggedUserNames() Get logged in users if current user has rights to access user list.
static java.util.Collection<ProjectDescriptor>	getProjectDescriptorsWithBranches(java.lang.Iterable<ProjectDescriptor> projectDescriptors) Invocation of this method returns a Collection of ProjectDescriptors of each branch in the given projectDescriptors.
static void	getProjectDescriptorsWithBranches(ProjectDescriptor descriptor, java.util.Collection<ProjectDescriptor> descriptorsWithBranches) Collects all project descriptors with branch info for the given project descriptor into the provided collection.
static java.lang.String	getProjectName(org.eclipse.emf.common.util.URI locationURI) Return project name for given URI.
static java.util.List<ProjectDescriptor>	getRemoteProjectDescriptors() Returns descriptors of projects stored on server.
static ITeamworkService	getTeamworkService() Get service for working with CEDW.
static java.util.Set<java.lang.String>	getUserNames() Get all users if current user has rights to access user list.
static java.util.List<IVersionDescriptor>	getVersions(ProjectDescriptor descriptor) Get all versions of given project.
static boolean	isNotifyOnNew(Project project, IAttachedProject iAttachedProject) Method returns if MagicDraw should notify about available project usage update.
static void	removeCommitTags(ProjectDescriptor descriptor, long version) Remove all tags from project version.
static void	setNotifyOnNew(Project project, IAttachedProject iAttachedProject, boolean notifyOnNew) Method sets if MagicDraw should notify about available project usage update.
static void	setProjectName(ProjectDescriptor project, java.lang.String newName) Rename project.
static void	updateModule(Project project, IAttachedProject module, ProjectDescriptor descriptor, long version) Change given module to another version or branch.
static void	updateProject(Project project) Updates given project.
static java.util.Map<IAttachedProject,java.lang.Boolean>	updateRequiredProjectUsages(Project project) This method updates project usages to newest version.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

EsiUtils

public EsiUtils()

Method Detail

getTeamworkService

public static ITeamworkService getTeamworkService()

Get service for working with CEDW.

Returns:

service for working with CEDW.

getLockService

@CheckForNull
public static ILockProjectService getLockService(@CheckForNull
                                                               Project project)

Provides api to check, request and release locks on various project data.

Returns:

lock service.

createProject

@CheckForNull
public static Project createProject(@Nonnull
                                                  java.lang.String name,
                                                  @CheckForNull
                                                  java.lang.String category)
                                           throws com.nomagic.ci.persistence.PersistenceException

Create ESI project. Project is created only if currently logged user rights allows to create projects.

Parameters:

name - project name.

category - project category.

Returns:

crated project.

Throws:

com.nomagic.ci.persistence.PersistenceException

commitProject

public static void commitProject(Project project,
                                 java.lang.String comment,
                                 @CheckForNull
                                 java.util.Collection<Element> unlockElements,
                                 @CheckForNull
                                 java.util.Collection<ModuleUsage> unlockModules,
                                 boolean unlockDecomposition,
                                 @CheckForNull
                                 java.util.List<java.lang.String> tags)

Commit project.

Parameters:

project - project

comment - comment.

unlockElements - elements to unlock when committing.

unlockModules - modules to unlock when committing.

unlockDecomposition - true if decomposition needs to be unlocked when committing.

tags - version tags to set.

exportEsiModule

@CheckForNull
public static IAttachedProject exportEsiModule(Project project,
                                                             java.util.Collection<Package> packages,
                                                             java.lang.String description,
                                                             java.lang.String moduleName)
                                                      throws java.lang.Exception

Exports module.

Parameters:

project - project.

packages - packages to export.

description - module description.

moduleName - name of module.

Returns:

exported module attached project.

Throws:

java.lang.Exception - in case of some problem

getRemoteProjectDescriptors

public static java.util.List<ProjectDescriptor> getRemoteProjectDescriptors()
                                                                     throws java.lang.Exception

Returns descriptors of projects stored on server.

Returns:

list of remote project descriptors.

Throws:

java.rmi.RemoteException - in case of some problem

java.lang.Exception

getVersions

public static java.util.List<IVersionDescriptor> getVersions(@Nonnull
                                                             ProjectDescriptor descriptor)

Get all versions of given project.

Parameters:

descriptor - project descriptor.

Returns:

list of version information.

addCommitTags

public static void addCommitTags(java.util.List<java.lang.String> tags,
                                 ProjectDescriptor descriptor,
                                 long version)

Add tags for given version.

Parameters:

tags - tags to add.

descriptor - project for which version tags is set.

version - version for which tags will be added.

getCommitTags

public static java.util.List<java.lang.String> getCommitTags(ProjectDescriptor descriptor,
                                                             long version)

Get tags names for project version.

Parameters:

descriptor - project descriptor.

version - version.

Returns:

list of tags for given version.

getCommitTagsInfo

public static java.util.List<com.nomagic.esi.api.info.TagInfo> getCommitTagsInfo(ProjectDescriptor descriptor,
                                                                                 long version)

Get tags for project version.

Parameters:

descriptor - project descriptor.

version - version.

Returns:

list of tags for given version.

getAllCommitTagsInfo

public static java.util.List<com.nomagic.esi.api.info.TagInfo> getAllCommitTagsInfo(ProjectDescriptor descriptor)

Get all tags for project.

Parameters:

descriptor - project descriptor.

Returns:

list of tags for given version.

removeCommitTags

public static void removeCommitTags(ProjectDescriptor descriptor,
                                    long version)

Remove all tags from project version.

Parameters:

descriptor - project descriptor.

version - version.

updateProject

public static void updateProject(Project project)

Updates given project. Project is activated before update.

Parameters:

project - teamwork project to update.

getProjectName

@CheckForNull
public static java.lang.String getProjectName(org.eclipse.emf.common.util.URI locationURI)

Return project name for given URI.

Parameters:

locationURI - project location.

Returns:

project name.

setProjectName

public static void setProjectName(ProjectDescriptor project,
                                  java.lang.String newName)
                           throws com.nomagic.ci.persistence.PersistenceException

Rename project.

Parameters:

project - project descriptor

newName - new project name.

Throws:

com.nomagic.ci.persistence.PersistenceException - in case of some problem

deleteProject

public static void deleteProject(ProjectDescriptor project)
                          throws com.nomagic.ci.persistence.PersistenceException

Delete project from repository.

Parameters:

project - project to delete.

Throws:

com.nomagic.ci.persistence.PersistenceException

getCategories

public static java.util.Set<com.nomagic.teamwork.common.projects.CategoryInfo> getCategories()

Returns:

all categories from server.

getCategoriesToProjects

public static java.util.Map<java.lang.String,java.util.List<ProjectDescriptor>> getCategoriesToProjects()
                                                                                                 throws java.lang.Exception

Get categories for projects.

Returns:

projects in categories.

Throws:

java.lang.Exception - in case of some problem

getCategoryID

@CheckForNull
public static java.lang.String getCategoryID(java.lang.String resourceID)

Gets category ID for specified twc project resource ID.

Parameters:

resourceID - twc project resource ID

Returns:

category ID or null if project is not in category

createCategory

public static void createCategory(java.lang.String name,
                                  java.lang.String description)

Create projects category in the server.

Parameters:

name - category name

description - category description

assignProjectToCategory

public static void assignProjectToCategory(ProjectDescriptor project,
                                           java.lang.String... categories)
                                    throws java.lang.Exception

Adds or remove project to/from categories. After this method project belongs only to categories specified for this method.

Parameters:

project - project to assign or remove from category.

categories - categories to which project will be assigned.

Throws:

java.lang.Exception - in case of some problem

deleteCategory

public static void deleteCategory(java.lang.String name)

Delete category with given name.

Parameters:

name - category name.

getBranches

public static java.util.Collection<EsiUtils.EsiBranchInfo> getBranches(ProjectDescriptor descriptor)

Get all branches for given project.

Parameters:

descriptor - project descriptor.

Returns:

branches for given project.

createBranch

public static void createBranch(ProjectDescriptor descriptor,
                                long version,
                                java.lang.String branchName,
                                java.lang.String branchDescription)

Create new branch for given project.

Parameters:

descriptor - project descriptor.

version - version from which branch

branchName - new branch name.

branchDescription - description of new branch.

Throws:

java.lang.RuntimeException - in case network or server error occurs when creating branch.

InsufficientPermissionsException - if currently logged in user does not have Administer Projects permission

getDescriptorByBranchID

public static ProjectDescriptor getDescriptorByBranchID(ProjectDescriptor project,
                                                        java.util.UUID branchID)

Get project descriptor for given branch. This descriptor can be used to load project from branch.

Parameters:

project - project descriptor.

branchID - branch id.

Returns:

project descriptor for given branch.

getDescriptorForBranch

public static ProjectDescriptor getDescriptorForBranch(ProjectDescriptor project,
                                                       java.lang.String branchName)

Get project descriptor for given branch. This descriptor can be used to load project from branch.

Parameters:

project - project descriptor.

branchName - branch name.

Returns:

project descriptor for given branch.

getDescriptorForVersion

public static ProjectDescriptor getDescriptorForVersion(ProjectDescriptor projectDescriptor,
                                                        IVersionDescriptor versionDescriptor)

Get descriptor for specific version. Can be used to open historic project version.

Parameters:

projectDescriptor - project descriptor.

versionDescriptor - version.

Returns:

descriptor for specific version.

deleteBranch

public static void deleteBranch(ProjectDescriptor descriptor,
                                java.lang.String branchName)

Delete project branch.

Parameters:

descriptor - project which branch will be deleted.

branchName - branch name to delete.

Throws:

InsufficientPermissionsException - if currently logged in user does not have Administer Projects permission

addToESI

public static IPrimaryProject addToESI(Project project,
                                       java.lang.String esiProjectName)
                                throws com.nomagic.ci.persistence.PersistenceException

Add project to the ESI server and open it.

Parameters:

project - project to add.

esiProjectName - project name in esi server.

Returns:

opened esi project.

Throws:

com.nomagic.ci.persistence.PersistenceException - in case of some problem

addToESI

public static IPrimaryProject addToESI(Project project,
                                       java.lang.String esiProjectName,
                                       @CheckForNull
                                       java.lang.String category,
                                       @CheckForNull
                                       java.lang.String comment,
                                       @CheckForNull
                                       java.util.List<java.lang.String> tags,
                                       @Nonnull
                                       java.util.Collection<ResolveLocalModuleInfo> resolveInfos)
                                throws com.nomagic.ci.persistence.PersistenceException

Add project to the ESI server and open it

Parameters:

project - the project to add

esiProjectName - the name for the new ESI project

category - the category to add the project to

comment - the commit comment

tags - the commit tags

resolveInfos - the module resolve info list

Returns:

the added project

Throws:

com.nomagic.ci.persistence.PersistenceException - exception if add fails

convertToLocal

@CheckForNull
public static Project convertToLocal(Project project,
                                                   java.io.File file)

Convert given project to local, save and reopen it.

Parameters:

project - project to convert

file - project file

Returns:

local project

getLoggedUserName

@CheckForNull
public static java.lang.String getLoggedUserName()

Returns the currently logged ESI user name.

Returns:

user name

getLoggedUserNames

public static java.util.Set<java.lang.String> getLoggedUserNames()

Get logged in users if current user has rights to access user list.

Returns:

all user names.

getUserNames

public static java.util.Set<java.lang.String> getUserNames()

Get all users if current user has rights to access user list.

Returns:

logged in user names.

updateModule

public static void updateModule(Project project,
                                IAttachedProject module,
                                ProjectDescriptor descriptor,
                                long version)
                         throws java.lang.Exception

Change given module to another version or branch.

Parameters:

project - project which module is switched.

module - module to switch.

descriptor - new module descriptor.

version - new module version

Throws:

java.lang.Exception - in case of some problem

setNotifyOnNew

public static void setNotifyOnNew(Project project,
                                  IAttachedProject iAttachedProject,
                                  boolean notifyOnNew)

Method sets if MagicDraw should notify about available project usage update.

Parameters:

project - Project to which's usage setting is applied.

iAttachedProject - Usage's attached project to which setting is applied.

notifyOnNew - Should notification be shown.

isNotifyOnNew

public static boolean isNotifyOnNew(Project project,
                                    IAttachedProject iAttachedProject)

Method returns if MagicDraw should notify about available project usage update. Return false by default.

Parameters:

project - Project to which's usage setting is applied.

iAttachedProject - Usage's attached project to which setting is applied.

Returns:

Should notification be shown. Returns false by default.

updateRequiredProjectUsages

public static java.util.Map<IAttachedProject,java.lang.Boolean> updateRequiredProjectUsages(Project project)
                                                                                     throws java.lang.Exception

This method updates project usages to newest version. Only usages which have isNotifyOnNew(Project, IAttachedProject) set to true are updated. It can be changed using setNotifyOnNew(Project, IAttachedProject, boolean). If project usages is locked by other user or can't be updated for other reasons its update will be skipped.

Parameters:

project - Project which usages are updated.

Returns:

Results map. Key - attached project which was updated, value - was update successful.

Throws:

java.lang.Exception - in case of some problem

See Also:

isNotifyOnNew(Project, IAttachedProject), setNotifyOnNew(Project, IAttachedProject, boolean)

applyProjectState

public static EsiUtils.ApplyProjectStateResult applyProjectState(Project source,
                                                                 Project target)
                                                          throws java.lang.IllegalArgumentException,
                                                                 ElementLockAcquisitionException,
                                                                 ModuleUsageLockAcquisitionException,
                                                                 OptionsLockAcquisitionException

Applies the state of the source project to the target project, or in other words, overwrites the content of the target project with the contents of the source project. The elements that are matched are updated, the not existing elements are removed, and new elements are added. Module usages are copied and modules are updated accordingly. To perform the operation successfully, all elements of the project, module usages, and options are locked. Any lock failure terminates the operation with a specific exception

Parameters:

source - the source project from which the state is copied

target - the target project to which the state is copied

Returns:

a structure that holds the result of the operation

Throws:

java.lang.IllegalArgumentException - if: 1. the projects are the same, 2. any of the projects are not ready, 3. any of the projects is not an ESI project, 4. the project IDs differ, 5. the target project is not editable

ElementLockAcquisitionException - if specific element could not be locked

ModuleUsageLockAcquisitionException - if specific module usage could not be locked

OptionsLockAcquisitionException - if specific options could not be locked

getLastVersion

public static long getLastVersion(ProjectDescriptor descriptor)

Get last project version number.

Parameters:

descriptor - project descriptor for ESI server project.

Returns:

last project version number, -1 - there is no such project or MagicDraw is not connected to the server.

Throws:

java.lang.RuntimeException - in case provided descriptor is not valid for current server.

getProjectDescriptorsWithBranches

public static java.util.Collection<ProjectDescriptor> getProjectDescriptorsWithBranches(java.lang.Iterable<ProjectDescriptor> projectDescriptors)

Invocation of this method returns a Collection of ProjectDescriptors of each branch in the given projectDescriptors.

Parameters:

projectDescriptors - descriptors of the projects, whose branch ProjectDescriptors should be returned

Returns:

project descriptors for each branch of the given projectDescriptors

getProjectDescriptorsWithBranches

public static void getProjectDescriptorsWithBranches(ProjectDescriptor descriptor,
                                                     java.util.Collection<ProjectDescriptor> descriptorsWithBranches)

Collects all project descriptors with branch info for the given project descriptor into the provided collection.

Parameters:

descriptor - project descriptor for which to collect project descriptors with branch info

descriptorsWithBranches - collection where to add the result

getBranchID

public static java.util.UUID getBranchID(org.eclipse.emf.common.util.URI locationURI)

Gets project branch ID.

Parameters:

locationURI - project location URI

Returns:

branch ID

getCurrentBranch

@CheckForNull
public static EsiUtils.EsiBranchInfo getCurrentBranch(IProject project)

Gets branch information for the given TWC project part. If TWC project part is not linked with TWC project (like standard profiles) then null will be returned.

Parameters:

project - project part

Returns:

branch information