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 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.Collection<EsiUtils.EsiBranchInfo>	getBranches(ProjectDescriptor descriptor) Get all branches for given project.
static java.util.Map<java.lang.String,java.util.List<ProjectDescriptor>>	getCategoriesToProjects() Get categories for projects.
static java.util.List<java.lang.String>	getCommitTags(ProjectDescriptor descriptor, long version) Get tags for project version.
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 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 com.nomagic.esi.api.EsiResource	getModelResource(com.nomagic.magicdraw.esi.project.project.EsiBaseProject project) Return resource for model and decomposition in esi project.
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 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, com.nomagic.magicdraw.esi.project.project.EsiAttachedProject 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.

getModelResource

public static com.nomagic.esi.api.EsiResource getModelResource(com.nomagic.magicdraw.esi.project.project.EsiBaseProject project)

Return resource for model and decomposition in esi project. Method assumes that esi project has same resource for model and decomposition.

Parameters:

project - esi project.

Returns:

model resource.

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 for project version.

Parameters:

descriptor - project descriptor.

version - version.

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

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

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

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

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.

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 desciptor.

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.

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

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,
                                com.nomagic.magicdraw.esi.project.project.EsiAttachedProject 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

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

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

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