Interface IModuleManager
- Since:
- 3.2
- Author:
- Miroslav Ruza
-
Field Summary
FieldsModifier and TypeFieldDescriptionstatic final String
Default module page layouter (always exists).static final ILocation
Default location for Documentsstatic final String
Paragraph module page layouter - work item is one paragraph.static final String
Section module page layouter - work item is section which contains heading and several paragraphs.static final String
Title, description and test steps layouter.static final String
Layouter for just the title.static final String
Title and test steps layouter. -
Method Summary
Modifier and TypeMethodDescriptionbranch()
Branches one or more Documents.branchModule
(IModule source, IProject targetProject, ILocation targetLocation, String targetName) Return brancher object which allows specifying optional parameters and executing the actual branching.createDerivedModule
(IModule source, IProject targetProject, ILocation targetLocation, String targetName, Set<String> derivedFields, ILinkRoleOpt derivedFromlinkRole, Set<String> notCopiedCustomFields, Set<String> convertedCopiedCustomFields) Create a new module from the module template to another (or same) project and location.createDerivedModule
(IModule source, IProject targetProject, ILocation targetLocation, String targetName, Set<String> derivedFields, ILinkRoleOpt derivedFromlinkRole, Set<String> notCopiedCustomFields, Set<String> convertedCopiedCustomFields, Map<IWorkItem, IWorkItem> modulesReuseWiMap) Create a new module from the module template to another (or same) project and location.createModule
(IProject project, ILocation location, String title, String moduleName, List<ITypeOpt> allowedWITypes, ILinkRoleOpt structureLinkRole, boolean parentToChild) Creates the module in given location with given parameters.createModule
(IProject project, ILocation location, String moduleName, List<ITypeOpt> allowedWITypes, ILinkRoleOpt structureLinkRole, boolean parentToChild) Creates the module in given location with given parameters.createWorkItem
(IProject project, ILocation location) Creates an instance of a Work Item, which (after being persistent) will be stored in the Module at the given location.duplicate
(IModule source, IProject targetProject, ILocation targetLocation, String targetName, ILinkRoleOpt linkRole, Set<String> keys, Set<String> exceptKeys, Set<String> notCopiedCustomFields, Set<String> convertedCopiedCustomFields) Duplicates the module to another (or same) project and location.duplicate
(IModule source, IProject targetProject, ILocation targetLocation, String targetName, ILinkRoleOpt linkRole, Set<String> keys, Set<String> exceptKeys, Set<String> notCopiedCustomFields, Set<String> convertedCopiedCustomFields, Map<IWorkItem, IWorkItem> modulesReuseWiMap) Duplicates the module to another (or same) project and location.boolean
existModule
(IProject project, ILocation location) Checks if the module in given location exists.getContainingModule
(IWorkItem item) Retrieve a module which contains the Work Item (if any)getFolderWorkItemsQuery
(IProject project, ILocation location) Returns a query that gets a list of Work Items stored in Documents in the given folder and its sub-folders.getHeadingType
(IProject project) Returns Work Item type of Document headings in the project.Retrieves the module with the given location.getModulePageLayouter
(String name) Returns module page layouter with given name.getModules
(IProject project, ILocation location) Retrieves the modules contained in the given location.getModuleWorkItems
(IProject project, String query, String sort, String moduleFolder, int limit) Returns Work Items contained by modules from given project, query and optional module foldergetModuleWorkItemsQuery
(IProject project, ILocation location) Returns the query to get the list of items contained in the given Document.getModuleWorkItemsQuery
(IProject project, ILocation location, boolean excludeUnreferenced) In addition togetModuleWorkItemsQuery(IProject, ILocation)
, the query has the option to exclude unreferenced Work Items from the query results.Returns the names under which are the layouters registered.getSubFolders
(IProject project, ILocation location) Retrieves the folders with Documents below the given location relative to the Documents' root in the given project.boolean
isDerivedFromLink
(IWorkItem from, ILinkRoleOpt role, IWorkItem to) Checks if this link is module derived from link.boolean
Checks if the given Work Item is linked in a module storageboolean
isModuleItem
(IWorkItem item) Checks if the given Work Item is stored in a module storageboolean
isModuleStructureLink
(IWorkItem from, ILinkRoleOpt role, IWorkItem to) Checks if this link is module structure link.void
Moves workitems out from modules to normal XML storage.Moves workitems out from modules to normal XML storage and reports which were skipped and which additional were moved.void
registerModulePageLayouter
(String name, IModulePageLayouter layouter) Registers module page layouter.void
Unregisters module page layouter.updateDerivedModule
(IModule module) Updates a derived module to the new revision (baseline).void
updateDerivedModule
(IModule module, String revision, Set<String> notCopiedCustomFields, Set<String> convertedCopiedCustomFields) Shortcut forupdateDerivedModule(IModule, String, Set, Set, boolean)
with autoSuspect set to false.void
updateDerivedModule
(IModule module, String revision, Set<String> notCopiedCustomFields, Set<String> convertedCopiedCustomFields, boolean autoSuspect) Updates a derived module to the new revision (baseline).void
updateWILinksAfterModuleReuse
(Map<IWorkItem, IWorkItem> modulesReuseWiMap, boolean keepRelative, boolean removeOutgoing) Updates inter-module links of Work Items after reuse of one or more modules
-
Field Details
-
DEFAULT_SPACE_LOCATION
Default location for Documents- Since:
- 3.5
-
DEFAULT_LAYOUTER
Default module page layouter (always exists).- Since:
- 3.5
- See Also:
-
PARAGRAPH_LAYOUTER
Paragraph module page layouter - work item is one paragraph.- Since:
- 3.5
- See Also:
-
SECTION_LAYOUTER
Section module page layouter - work item is section which contains heading and several paragraphs.- Since:
- 3.5
- See Also:
-
TITLE_TESTSTEPS_LAYOUTER
Title and test steps layouter.- Since:
- 3.6.3
- See Also:
-
TITLE_DESC_TESTSTEPS_LAYOUTER
Title, description and test steps layouter.- Since:
- 3.6.3
- See Also:
-
TITLE_LAYOUTER
Layouter for just the title.- Since:
- 3.23.10
- See Also:
-
-
Method Details
-
createWorkItem
Creates an instance of a Work Item, which (after being persistent) will be stored in the Module at the given location.Note, that this function just creates the java instance, which is not persisted in any way and call to the
IPObject.save()
method is necessary to persist it.- Parameters:
project
-location
- Of existing module - relative to modules root in the given project.- Returns:
- the unpersisted
IWorkItem
-
getSubFolders
Retrieves the folders with Documents below the given location relative to the Documents' root in the given project.Note: Folder in this interface has a different meaning than in
IFolderManager
. Here it refers to a folder in the repository. These folders have a different hierarchy thanIFolder
s. (There is only a single folder level in the repository.)- Parameters:
project
-location
- parent location, relative to Documents' root in the given project.- Returns:
- list of
ILocation
, nevernull
-
getModules
Retrieves the modules contained in the given location. It the location is a location of a module a collection with the single module will be returned.- Parameters:
project
-location
- location to retrieve modules - relative to modules root in the given project.- Returns:
- sorted list of
IModule
, never return thenull
, returns empty list if the location does not exist.
-
getModule
Retrieves the module with the given location. -
existModule
Checks if the module in given location exists. AnILocation
location needs to be passed with a revision number to return the correct result. (In case the module was moved.) To do this, use thesetRevision(string revision)
method. For example:IProject project = trackerService.getProjectsService().getProject(projectId); ILocation location = project.getLocation().append(myModuleDoc).setRevision("2126"); if (trackerService.getModuleManager().existModule(project,location)) { //DO SOMETHING }
- Parameters:
project
-location
- location of module - relative to modules root in the given project.
-
getContainingModule
Retrieve a module which contains the Work Item (if any)- Parameters:
item
- item to retrieve the module- Returns:
- module or
null
-
isModuleItem
Checks if the given Work Item is stored in a module storage- Parameters:
item
- item to check- Returns:
true
if the object stored in a module
-
isExternalModuleItem
Checks if the given Work Item is linked in a module storage- Parameters:
item
- item to check- Returns:
true
if the object linked in a module- Since:
- 3.6.0
-
createModule
IModule createModule(@NotNull IProject project, @Nullable ILocation location, @NotNull String moduleName, @Nullable List<ITypeOpt> allowedWITypes, @NotNull ILinkRoleOpt structureLinkRole, boolean parentToChild) Creates the module in given location with given parameters.- Parameters:
project
- - project theIProject
object to create the module forlocation
- - Document space location with one component (e.g.DEFAULT_SPACE_LOCATION
for default space) or null for old-style modulesmoduleName
- - name of the new moduleallowedWITypes
- - allows exactly one - must be specifiedstructureLinkRole
- - required, role which define the hierarchy of work items inside the moduleparentToChild
- - true when the structure link goes from parent to child. Allows only false- Returns:
- the unpersisted module (caller must call save() on the returned module to persist it)
-
createModule
IModule createModule(@NotNull IProject project, @Nullable ILocation location, @Nullable String title, @NotNull String moduleName, @Nullable List<ITypeOpt> allowedWITypes, @NotNull ILinkRoleOpt structureLinkRole, boolean parentToChild) Creates the module in given location with given parameters.- Parameters:
project
- - project theIProject
object to create the module forlocation
- - Document space location with one component (e.g.DEFAULT_SPACE_LOCATION
for default space) or null for old-style modulestitle
- - title of the new modulemoduleName
- - name of the new moduleallowedWITypes
- - allows exactly one - must be specifiedstructureLinkRole
- - required, role which define the hierarchy of work items inside the moduleparentToChild
- - true when the structure link goes from parent to child. Allows only false- Returns:
- the unpersisted module (caller must call save() on the returned module to persist it)
- Since:
- 3.8.2
-
getModuleWorkItemsQuery
Returns the query to get the list of items contained in the given Document. The query matches both external Work Items referenced in the Document and Work Items stored in the Document. Consider usingIModule.createWorkItemsQuery()
instead of this method, especially if you need to combine the returned query with other query.- Parameters:
project
-location
- The Document's location relative to the Document root in the given project.- Returns:
- Query, which can be passed e.g. to
ITrackerService.queryWorkItems(String, String)
-
getModuleWorkItemsQuery
In addition togetModuleWorkItemsQuery(IProject, ILocation)
, the query has the option to exclude unreferenced Work Items from the query results. Consider usingIModule.createWorkItemsQuery()
instead of this method, especially if you need to combine the returned query with another query.- Since:
- 3.6.3
-
getFolderWorkItemsQuery
Returns a query that gets a list of Work Items stored in Documents in the given folder and its sub-folders. The query excludes external Work Items contained in the Documents that are stored in the folder.Note: Folder in this interface has a different meaning than in
IFolderManager
. Here it refers to a real folder in the repository. These folders have a different hierarchy thanIFolder
s. (There is only a single folder level in the repository.)- Parameters:
project
-location
- A folder location relative to the Documents' root in the given project.- Returns:
- Query, that can be passed e.g. to
ITrackerService.queryWorkItems(String, String)
-
isModuleStructureLink
Checks if this link is module structure link.- Parameters:
from
-role
-to
-
-
duplicate
IModule duplicate(IModule source, IProject targetProject, ILocation targetLocation, String targetName, ILinkRoleOpt linkRole, Set<String> keys, Set<String> exceptKeys, Set<String> notCopiedCustomFields, Set<String> convertedCopiedCustomFields) Duplicates the module to another (or same) project and location.- Parameters:
source
- - module to copytargetProject
- - project where the copied module will be createdtargetLocation
- - parent folder where to create the module - relative to modules root in the given project (ignored)targetName
- - name of the copied modulelinkRole
- - can be null, if not than links with this role will be created from the copied to the original work itemkeys
- - which keys to copy, can be null, than all values are copied (ignored)exceptKeys
- - which keys to not copy, can be null (ignored)notCopiedCustomFields
- - keys of the custom fields which cannot be copied because of different types will be added to this collection, must be modifiable Set, cannot be nullconvertedCopiedCustomFields
- - keys of the custom fields which have different type, but the value was converted will be added to this collection, must be modifiable Set, cannot be null- Returns:
- the created module;
-
duplicate
IModule duplicate(IModule source, IProject targetProject, ILocation targetLocation, String targetName, ILinkRoleOpt linkRole, Set<String> keys, Set<String> exceptKeys, Set<String> notCopiedCustomFields, Set<String> convertedCopiedCustomFields, Map<IWorkItem, IWorkItem> modulesReuseWiMap) Duplicates the module to another (or same) project and location.- Parameters:
source
- - module to copytargetProject
- - project where the copied module will be createdtargetLocation
- - parent folder where to create the module - relative to modules root in the given project (ignored)targetName
- - name of the copied modulelinkRole
- - can be null, if not than links with this role will be created from the copied to the original work itemkeys
- - which keys to copy, can be null, than all values are copied (ignored)exceptKeys
- - which keys to not copy, can be null (ignored)notCopiedCustomFields
- - keys of the custom fields which cannot be copied because of different types will be added to this collection, must be modifiable Set, cannot be nullconvertedCopiedCustomFields
- - keys of the custom fields which have different type, but the value was converted will be added to this collection, must be modifiable Set, cannot be nullmodulesReuseWiMap
- - keeps track of old and created workitems when reusing more than one module. Can benull
, seeupdateWILinksAfterModuleReuse(Map, boolean, boolean)
}- Returns:
- the created module;
- Since:
- 3.4.1
-
createDerivedModule
IModule createDerivedModule(IModule source, IProject targetProject, ILocation targetLocation, String targetName, Set<String> derivedFields, ILinkRoleOpt derivedFromlinkRole, Set<String> notCopiedCustomFields, Set<String> convertedCopiedCustomFields) Create a new module from the module template to another (or same) project and location.- Parameters:
source
- - module template (throws an InvalidArgumentException if source is derived already), it might be historical objecttargetProject
- - project where the copied module will be createdtargetLocation
- - parent folder where to create the module - relative to modules root in the given project (ignored)targetName
- - name of the copied module *derivedFields
- - set fields that will be derived in new modulederivedFromlinkRole
- - link role used to link derived item to source item, null = use defaultnotCopiedCustomFields
- - keys of the custom fields which cannot be copied because of different types will be added to this collection, must be modifiable Set, cannot be nullconvertedCopiedCustomFields
- - keys of the custom fields which have different type, but the value was converted will be added to this collection, must be modifiable Set, cannot be null- Returns:
- the created module;
- Since:
- 3.3
-
createDerivedModule
IModule createDerivedModule(IModule source, IProject targetProject, ILocation targetLocation, String targetName, Set<String> derivedFields, ILinkRoleOpt derivedFromlinkRole, Set<String> notCopiedCustomFields, Set<String> convertedCopiedCustomFields, Map<IWorkItem, IWorkItem> modulesReuseWiMap) Create a new module from the module template to another (or same) project and location.- Parameters:
source
- - module template (throws an InvalidArgumentException if source is derived already), it might be historical objecttargetProject
- - project where the copied module will be createdtargetLocation
- - parent folder where to create the module - relative to modules root in the given project (ignored)targetName
- - name of the copied module *derivedFields
- - set fields that will be derived in new modulederivedFromlinkRole
- - link role used to link derived item to source item, null = use defaultnotCopiedCustomFields
- - keys of the custom fields which cannot be copied because of different types will be added to this collection, must be modifiable Set, cannot be nullconvertedCopiedCustomFields
- - keys of the custom fields which have different type, but the value was converted will be added to this collection, must be modifiable Set, cannot be nullmodulesReuseWiMap
- - keeps track of old and created workitems when reusing more than one module. Can benull
, seeupdateWILinksAfterModuleReuse(java.util.Map<com.polarion.alm.tracker.model.IWorkItem, com.polarion.alm.tracker.model.IWorkItem>, boolean, boolean)
}- Returns:
- the created module;
- Since:
- 3.4.1
-
updateWILinksAfterModuleReuse
void updateWILinksAfterModuleReuse(@NotNull Map<IWorkItem, IWorkItem> modulesReuseWiMap, boolean keepRelative, boolean removeOutgoing) Updates inter-module links of Work Items after reuse of one or more modules- Parameters:
modulesReuseWiMap
- map filled by duplicate methodkeepRelative
- - means to keep relative Work Item links between reused modulesremoveOutgoing
- - remove other outgoing Work Item links Usage:IModule sourceModule1, sourceModule2; IModuleManager mm; Map<IWorkItem, IWorkItem> modulesReuseWiMap = new HashMap<IWorkItem, IWorkItem>(); mm.duplicate(sourceModule1, targetProject, targetLocation, targetName, linkRole, keys, exceptKeys, notCopiedCustomFields, convertedCopiedCustomFields, modulesReuseWiMap); mm.duplicate(sourceModule2, targetProject, targetLocation, targetName, linkRole, keys, exceptKeys, notCopiedCustomFields, convertedCopiedCustomFields, modulesReuseWiMap); mm.updateWILinksAfterModuleReuse(modulesReuseWiMap, keepRelative, removeOutgoing);
That will ensure that any link between WI from sourceModule1 and WI from sourceModule2 will be kept after these modules are reused (duplicated or derived).- Since:
- 3.4.1
-
updateDerivedModule
void updateDerivedModule(@NotNull IModule module, @Nullable String revision, @Nullable Set<String> notCopiedCustomFields, @Nullable Set<String> convertedCopiedCustomFields) Shortcut forupdateDerivedModule(IModule, String, Set, Set, boolean)
with autoSuspect set to false.- Since:
- 3.3
-
updateDerivedModule
void updateDerivedModule(@NotNull IModule module, @Nullable String revision, @Nullable Set<String> notCopiedCustomFields, @Nullable Set<String> convertedCopiedCustomFields, boolean autoSuspect) Updates a derived module to the new revision (baseline).- Parameters:
module
- the derived module to be updatedrevision
- null = headnotCopiedCustomFields
- custom fields that could not be copied (output); note that since 3.5.1 this is always an empty set, because the 'incompatible custom fields' feature is now used for custom fields of this typeconvertedCopiedCustomFields
- custom fields which were converted, rather than exact copies (output); since 3.5.1 this also includes incompatible custom fieldsautoSuspect
- if set to 'true' Work Item links leading to updated Work Items will be flagged as 'Suspect'- Since:
- 3.5.3
-
updateDerivedModule
Updates a derived module to the new revision (baseline). Returns a builder that allows you to set options for the update. It also allows for the removal of outgoing Work Item links.IDerivedModuleUpdater
. Call build() at the end.- Parameters:
module
- - The derived module to be updated.- Since:
- 3.21.2
-
isDerivedFromLink
Checks if this link is module derived from link.- Parameters:
from
-role
-to
-- Since:
- 3.3
-
branchModule
IModuleBrancher branchModule(IModule source, IProject targetProject, ILocation targetLocation, String targetName) Return brancher object which allows specifying optional parameters and executing the actual branching.- Parameters:
source
- - requiredtargetProject
- - requiredtargetLocation
- - required relative location of the module parent folder inside modules folder in repositorytargetName
- - required- Returns:
- brancher object which allows specifying optional parameters and executing the actual branching.
- Throws:
IllegalArgumentException
- if source is null, unresolvable or old style moduleIllegalArgumentException
- if targetProject is null or unresolvableIllegalArgumentException
- if targetLocation is null or unresolvableIllegalArgumentException
- if targetName is null or empty- Since:
- 3.6.0
-
branch
Branches one or more Documents.- Since:
- 3.23.10
-
moveOutFromModules
Moves workitems out from modules to normal XML storage. Workitems which are not in any module are skipped.- Parameters:
wis
-- Since:
- 3.3
-
moveOutFromModulesWithReport
Moves workitems out from modules to normal XML storage and reports which were skipped and which additional were moved. Workitems which are not in any module are skipped. Note it moves also all workitems which are (direct or indirect) children of passed workitems.- Parameters:
wis
-- Returns:
- report about moved work items (not
null
). - Since:
- 3.4
-
getModulePageLayouter
Returns module page layouter with given name.- Parameters:
name
- layouter's name (notnull
)- Returns:
- layouter or
null
if not registered - Since:
- 3.5
-
registerModulePageLayouter
Registers module page layouter.It is permitted to register one layouter under more names. It is permitted to reregister previously registered name.
- Parameters:
name
- layouter's name (notnull
)layouter
- layouter (notnull
)- Since:
- 3.5
-
unregisterModulePageLayouter
Unregisters module page layouter.- Parameters:
name
- layouter's name (notnull
)- Since:
- 3.8.1
-
getRegisteredModulePageLayouterNames
Collection<String> getRegisteredModulePageLayouterNames()Returns the names under which are the layouters registered.- Since:
- 3.5
-
getModuleWorkItems
List<IWorkItem> getModuleWorkItems(IProject project, String query, String sort, String moduleFolder, int limit) Returns Work Items contained by modules from given project, query and optional module folder- Parameters:
project
- limit result to Work Items from particular project, null = result is not limited to project but to all projectsquery
- notnull
sort
- the format is same as forIIndexSearch.sort(String)
moduleFolder
- limit result to Work Items from particular module folder, null = result is limited to all module folder excluding module rootlimit
- maximal size of returned list, negative number means no limit- Returns:
- sorted list of
IWorkItem
, never return thenull
- Since:
- 3.5
-
getHeadingType
Returns Work Item type of Document headings in the project.- Parameters:
project
-- Returns:
- type option, not
null
- Since:
- 3.5.2
-