Package com.polarion.alm.tracker

Interface IModuleManager

public interface IModuleManager
The term "module" in older methods has been replaced with "Document" in both the UI and any new methods that are added.
Since:
3.2
Author:
Miroslav Ruza

  • Field Details

    • DEFAULT_SPACE_LOCATION

      static final ILocation DEFAULT_SPACE_LOCATION
      Default location for Documents
      Since:
      3.5

    • DEFAULT_LAYOUTER

      static final String DEFAULT_LAYOUTER
      Default module page layouter (always exists).
      Since:
      3.5
      See Also:

    • PARAGRAPH_LAYOUTER

      static final String PARAGRAPH_LAYOUTER
      Paragraph module page layouter - work item is one paragraph.
      Since:
      3.5
      See Also:

    • SECTION_LAYOUTER

      static final String SECTION_LAYOUTER
      Section module page layouter - work item is section which contains heading and several paragraphs.
      Since:
      3.5
      See Also:

    • TITLE_TESTSTEPS_LAYOUTER

      static final String TITLE_TESTSTEPS_LAYOUTER
      Title and test steps layouter.
      Since:
      3.6.3
      See Also:

    • TITLE_DESC_TESTSTEPS_LAYOUTER

      static final String TITLE_DESC_TESTSTEPS_LAYOUTER
      Title, description and test steps layouter.
      Since:
      3.6.3
      See Also:

    • TITLE_LAYOUTER

      static final String TITLE_LAYOUTER
      Layouter for just the title.
      Since:
      3.23.10
      See Also:

  • Method Details

    • createWorkItem

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

      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

      List<ILocation> getSubFolders(IProject project, ILocation location)
      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 than IFolders. (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, never null

    • getModules

      List<IModule> getModules(IProject project, ILocation location)
      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 the null, returns empty list if the location does not exist.

    • getModule

      IModule getModule(IProject project, ILocation location)
      Retrieves the module with the given location.
      Parameters:
      project -
      location - location of retrieved module - relative to modules root in the given project. Use location with revision set to retrieve a particular revision of the module.
      Returns:
      IModule, or null if Location doesn't point to valid IModule

    • existModule

      boolean existModule(IProject project, ILocation location)
      Checks if the module in given location exists. An ILocation location needs to be passed with a revision number to return the correct result. (In case the module was moved.) To do this, use the setRevision(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

      IModule getContainingModule(IWorkItem item)
      Retrieve a module which contains the Work Item (if any)
      Parameters:
      item - item to retrieve the module
      Returns:
      module or null

    • isModuleItem

      boolean isModuleItem(IWorkItem item)
      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

      boolean isExternalModuleItem(IWorkItem item)
      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 the IProject object to create the module for
      location - - Document space location with one component (e.g. DEFAULT_SPACE_LOCATION for default space) or null for old-style modules
      moduleName - - name of the new module
      allowedWITypes - - allows exactly one - must be specified
      structureLinkRole - - required, role which define the hierarchy of work items inside the module
      parentToChild - - 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 the IProject object to create the module for
      location - - Document space location with one component (e.g. DEFAULT_SPACE_LOCATION for default space) or null for old-style modules
      title - - title of the new module
      moduleName - - name of the new module
      allowedWITypes - - allows exactly one - must be specified
      structureLinkRole - - required, role which define the hierarchy of work items inside the module
      parentToChild - - 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

      String getModuleWorkItemsQuery(IProject project, ILocation location)
      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 using IModule.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

      String getModuleWorkItemsQuery(IProject project, ILocation location, boolean excludeUnreferenced)
      In addition to getModuleWorkItemsQuery(IProject, ILocation), the query has the option to exclude unreferenced Work Items from the query results. Consider using IModule.createWorkItemsQuery() instead of this method, especially if you need to combine the returned query with another query.
      Since:
      3.6.3

    • getFolderWorkItemsQuery

      String 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. 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 than IFolders. (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

      boolean isModuleStructureLink(IWorkItem from, ILinkRoleOpt role, IWorkItem to)
      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 copy
      targetProject - - project where the copied module will be created
      targetLocation - - parent folder where to create the module - relative to modules root in the given project (ignored)
      targetName - - name of the copied module
      linkRole - - can be null, if not than links with this role will be created from the copied to the original work item
      keys - - 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 null
      convertedCopiedCustomFields - - 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 copy
      targetProject - - project where the copied module will be created
      targetLocation - - parent folder where to create the module - relative to modules root in the given project (ignored)
      targetName - - name of the copied module
      linkRole - - can be null, if not than links with this role will be created from the copied to the original work item
      keys - - 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 null
      convertedCopiedCustomFields - - 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
      modulesReuseWiMap - - keeps track of old and created workitems when reusing more than one module. Can be null, see updateWILinksAfterModuleReuse(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 object
      targetProject - - project where the copied module will be created
      targetLocation - - 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 module
      derivedFromlinkRole - - link role used to link derived item to source item, null = use default
      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 null
      convertedCopiedCustomFields - - 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 object
      targetProject - - project where the copied module will be created
      targetLocation - - 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 module
      derivedFromlinkRole - - link role used to link derived item to source item, null = use default
      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 null
      convertedCopiedCustomFields - - 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
      modulesReuseWiMap - - keeps track of old and created workitems when reusing more than one module. Can be null, see updateWILinksAfterModuleReuse(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 method
      keepRelative - - means to keep relative Work Item links between reused modules
      removeOutgoing - - 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 for updateDerivedModule(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 updated
      revision - null = head
      notCopiedCustomFields - 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 type
      convertedCopiedCustomFields - custom fields which were converted, rather than exact copies (output); since 3.5.1 this also includes incompatible custom fields
      autoSuspect - if set to 'true' Work Item links leading to updated Work Items will be flagged as 'Suspect'
      Since:
      3.5.3

    • updateDerivedModule

      @NotNull IDerivedModuleUpdater updateDerivedModule(@NotNull IModule module)
      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

      boolean isDerivedFromLink(IWorkItem from, ILinkRoleOpt role, IWorkItem to)
      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 - - required
      targetProject - - required
      targetLocation - - required relative location of the module parent folder inside modules folder in repository
      targetName - - required
      Returns:
      brancher object which allows specifying optional parameters and executing the actual branching.
      Throws:
      IllegalArgumentException - if source is null, unresolvable or old style module
      IllegalArgumentException - if targetProject is null or unresolvable
      IllegalArgumentException - if targetLocation is null or unresolvable
      IllegalArgumentException - if targetName is null or empty
      Since:
      3.6.0

    • branch

      @NotNull IBranchDocumentsCommand branch()
      Branches one or more Documents.
      Since:
      3.23.10

    • moveOutFromModules

      void moveOutFromModules(Collection<IWorkItem> wis)
      Moves workitems out from modules to normal XML storage. Workitems which are not in any module are skipped.
      Parameters:
      wis -
      Since:
      3.3

    • moveOutFromModulesWithReport

      IModule.IMoveReport moveOutFromModulesWithReport(Collection<IWorkItem> wis)
      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

      IModulePageLayouter getModulePageLayouter(String name)
      Returns module page layouter with given name.
      Parameters:
      name - layouter's name (not null)
      Returns:
      layouter or null if not registered
      Since:
      3.5

    • registerModulePageLayouter

      void registerModulePageLayouter(@NotNull String name, @NotNull IModulePageLayouter layouter)
      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 (not null)
      layouter - layouter (not null)
      Since:
      3.5

    • unregisterModulePageLayouter

      void unregisterModulePageLayouter(@NotNull String name)
      Unregisters module page layouter.
      Parameters:
      name - layouter's name (not null)
      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 projects
      query - not null
      sort - can be null, null = no sorting is applied
      moduleFolder - limit result to Work Items from particular module folder, null = result is limited to all module folder excluding module root
      limit - maximal size of returned list, negative number means no limit
      Returns:
      sorted list of IWorkItem, never return the null
      Since:
      3.5

    • getHeadingType

      ITypeOpt getHeadingType(IProject project)
      Returns Work Item type of Document headings in the project.
      Parameters:
      project -
      Returns:
      type option, not null
      Since:
      3.5.2