Package com.polarion.platform.persistence

Interface IDataService

public interface IDataService

  • Field Details

  • Method Details

    • isValidId

      boolean isValidId(String id)
      Test if a given string is a valid ID (primary key) for the PObject. Must not have leading or trailing white spaces or contain ID_INVALID_CHARS characters.
      Parameters:
      id -
      Returns:
      true if the ID is valid.

    • getPrototype

      IPrototype getPrototype(String name)
      This is a shortcut for calling the prototype service.
      Parameters:
      name -
      Returns:
      the IPrototype with the specified name, null if no such prototype exists.
      See Also:

    • getCustomFieldsService

      ICustomFieldsService getCustomFieldsService()
      Returns:
      The custom features service used by this data service. Not null.

    • getCalculatedFieldsService

      ICalculatedFieldsService getCalculatedFieldsService()
      Returns:
      the derived fields service, not null
      Since:
      3.3.0

    • getObjectHierarchyProvider

      IObjectHierarchyProvider getObjectHierarchyProvider()
      Returns:
      the object hierarchy provider, not null
      Since:
      3.3.0

    • getQueryHelper

      IQueryHelper getQueryHelper()
      Returns:
      Returns the tool for manipulating queries (e.g. composing complex ones from simple ones).

    • getEventManager

      IEventManager getEventManager()
      Returns:
      The event manager instance, where it's possible to listen to events on objects stored in the persistence.

    • searchInstances

      IPObjectList searchInstances(IPrototype proto, String query, String sort)
      Searches for objects of the given type matching the query. A shortcut for

      searchInstances(proto.getName(), query, sort);

      Note: In general, the searching does not preserve inheritance. In other words, if Proto2 extends Proto1, then searching for Proto1 does not return the instances of Proto2.

      Parameters:
      proto -
      query -
      sort - The format is same as for IIndexSearch.sort(String).
      Returns:
      a IPObjectList containing the result of the query.

    • searchInstances

      IPObjectList searchInstances(IPrototype proto, String query, String sort, int resultLimit)
      Searches for objects of the given type matching the query. A shortcut for

      searchInstances(proto.getName(), query, sort, resultLimit);

      Note: In general, the searching does not preserve inheritance. In other words, if Proto2 extends Proto1, then searching for Proto1 does not return the instances of Proto2.

      Parameters:
      proto -
      query -
      sort - The format is same as for IIndexSearch.sort(String).
      resultLimit - The maximum size of the returned list. A negative number means it's unlimited.
      Returns:
      a IPObjectList containing the result of the query.

    • searchInstances

      IPObjectList searchInstances(String index, String query, String sort)
      Searches the objects in the given index. In a typical case, the index name corresponds to the prototype name, however, there can be some additional indices defined, that don't correspond to a particular prototype.
      Parameters:
      index -
      query -
      sort - The format is same as for IIndexSearch.sort(String).
      Returns:
      a IPObjectList containing the result of the query

    • searchInstancesInBaseline

      IPObjectList searchInstancesInBaseline(String index, String query, String sort, String revision)
      Searches the objects in the given index from a given revision. In a typical case, the index name corresponds to the prototype name, however, there can be some additional indices defined, that don't correspond to a particular prototype.
      Parameters:
      index -
      query -
      sort - The format is same as for IIndexSearch.sort(String)
      revision -
      Returns:
      a IPObjectList containing the result of the query
      Since:
      3.6.0

    • searchInstances

      IPObjectList searchInstances(String index, String query, String sort, int resultLimit)
      Searches the objects in the given index. Only first resultLimit items are returned if there are more objects found.

      In a typical case, the index name corresponds to the prototype name, however, there can be some additional indices defined, that don't correspond to a particular prototype.

      Parameters:
      index -
      query -
      sort - The format is same as for IIndexSearch.sort(String).
      resultLimit - maximal size of returned list, negative number means no limit
      Returns:
      a IPObjectList containing the result of the query

    • searchInstancesInBaseline

      IPObjectList searchInstancesInBaseline(String index, String query, String sort, int resultLimit, String revision)
      Searches the objects in the given index from a given revision. Only first resultLimit items are returned if there are more objects found.

      In a typical case, the index name corresponds to the prototype name, however, there can be some additional indices defined, that don't correspond to a particular prototype.

      Parameters:
      index -
      query -
      sort - The format is same as for IIndexSearch.sort(String).
      resultLimit - The maximum size of the returned list. A negative number means it's unlimited.
      revision - baseline revision, or null not to search in a baseline.
      Returns:
      a IPObjectList containing the result of the query.
      Since:
      3.6.0

    • sqlSearch

      @NotNull <T extends IPObject> IPObjectList<T> sqlSearch(@NotNull String sqlQuery)
      Searches the persistent objects by executing the specified SQL-query in the database for the current revision.

      You can also use search().database(). instances(String) for the same purpose. SQL searches should only be used for advanced querying/counting when joins and the other SQL-capabilities, that cannot be achieved using Lucene queries, are needed. In other cases the IDataService's search/count methods that work with Lucene queries are preferred. For example, searchInstances(String, String, String), getInstancesCount(String, String), etc.

      Parameters:
      sqlQuery -
      Returns:
      a IPObjectList containing the objects found as a result of the query execution.
      Since:
      3.6.0

    • sqlSearchInBaseline

      @NotNull <T extends IPObject> IPObjectList<T> sqlSearchInBaseline(@NotNull String sqlQuery, @Nullable String revision)
      Searches the persistent objects by executing the specified SQL-query in the database for the specified revision. *

      You can also use search().database(). instancesInBaseline(String, String) for the same purpose. SQL searches should only be used for advanced querying/counting when joins and the other SQL-capabilities, that cannot be achieved using Lucene queries, are needed. In other cases the IDataService's search/count methods that work with Lucene queries are preferred. For example, searchInstances(String, String, String), getInstancesCount(String, String), etc.

      Parameters:
      sqlQuery -
      revision - A Baseline revision in which to search. If null, search in the current revision.
      Returns:
      a IPObjectList containing the objects found as a result of the query execution.
      Since:
      3.6.1

    • search

      @NotNull IObjectsSearch search()
      Returns an instance of IObjectsSearch that allows for the search and count of the persistent objects in various secondary data sources.
      Returns:
      An instance of IObjectsSearch.
      Since:
      3.19.3

    • getInstancesCount

      int getInstancesCount(String proto, String query)
      Returns the count of instances for a query.
      Parameters:
      proto -
      query -
      Returns:
      the number instances with a specified prototype for the query.
      See Also:

    • getInstancesCount

      int getInstancesCount(IPrototype proto, String query)
      Returns the instances count for a query.
      Parameters:
      proto -
      query -
      Returns:
      the number instances for the query.
      See Also:

    • getInstance

      IPObject getInstance(SubterraURI uri)
      Returns an instance of the correct type for the given URI. The object is unresolved and it is not guaranteed that it exists.
      Parameters:
      uri - The URI of an object. Can't be a null
      Returns:
      the IPObject implementing the model-specific interface (if registered) or just a generic IPObject if none is specified

    • getInstance

      IPObject getInstance(IObjectId id)
      Returns an instance of the correct type for the object id.
      Parameters:
      id - - ObjectId of a retrieved object. Can't be a null
      Returns:
      The IPObject implementing the model-specific interface (if registered) or just a generic IPObject if none is specified.

    • getInstances

      @NotNull IPObjectList getInstances(@NotNull List<SubterraURI> uris)
      Parameters:
      uris - The list of SubterraURIs
      Returns:
      The list with these objects. The objects in the list are not resolved. This operation does not contact the back-end.

    • createInstance

      IPObject createInstance(String prototypeName)
      Creates the new instance of the given prototype. The object is not yet persistent and an attempt to read its ID or to link it to other objects (e.g. otherObject.setXXX(created) will result in an exception. Performing the save operation on the object will create the object persistently and makes its ID readable.
      Parameters:
      prototypeName -
      Returns:
      a new IPObject instance for the given prototypeName
      Throws:
      ReadOnlyException - If the prototype is read only.
      See Also:

    • save

      void save(IPObject instance) throws ReadOnlyException
      Throws:
      ReadOnlyException

    • save

      void save(IPObjectList instances) throws ReadOnlyException
      Only the instances with IPObject.isModified() == true are saved. Instances that are not resolved are ignored. Instances, that did not exist before, are created.
      Parameters:
      instances -
      Throws:
      ReadOnlyException

    • resolve

      void resolve(IPObject instance)
      Resolves the IPObject with data from the server. If the object is already resolved, it does nothing.
      Parameters:
      instance -

    • resolve

      void resolve(IPObjectList instances)
      A more efficient way for resolving more objects at once, than to resolve each one individually.
      Parameters:
      instances - List of IPObject

    • delete

      void delete(IPObject instance) throws ReadOnlyException
      Throws:
      ReadOnlyException

    • delete

      void delete(IPObjectList instances) throws ReadOnlyException
      Throws:
      ReadOnlyException

    • createCollectionForKey

      ITypedList createCollectionForKey(IPObject pobject, String key, List data)
      Creates an instance of a collection object, corresponding to the model definition. Use the dot notation, if the collection is under another structure or collection (e.g. mystructure.substructure).
      Parameters:
      pobject - object (not null)
      key -
      data - This is the low-level data, that will be wrapped by the structure. An empty ArrayList should be passed in when the low level data is not available.
      Returns:
      the ITypedList instance created for the specified key
      Since:
      3.1.2
      See Also:

    • createCollectionForTypeId

      ITypedList createCollectionForTypeId(IPObject pobject, String listTypeId, List data)
      Creates the instance of the list object, that corresponds to the model definition.
      Parameters:
      pobject - object (not null)
      listTypeId -
      data -
      Returns:
      the ITypedList instance created for the specified listTypeId
      Since:
      3.1.2

    • createStructureForKey

      IStructure createStructureForKey(IPObject pobject, String key, Map data)
      Creates the instance of the structure object, that corresponds to the model definition. Use the dot notation, if the structure is under another structure or collection (e.g. mystructure.substructure).
      Parameters:
      pobject - object (not null)
      key -
      data - This is low-level data, that will be wrapped by the structure. An empty HashMap should be passed on when the low level data is not available.
      Returns:
      the IStructure instance created for the specified key
      Since:
      3.1.2
      See Also:

    • createStructureForTypeId

      IStructure createStructureForTypeId(IPObject pobject, String structureId, Map data)
      Creates the instance of a structure object, that corresponds to the model definition.
      Parameters:
      pobject - object (not null)
      structureId -
      data -
      Returns:
      the IStructure instance created for the specified structureId
      Since:
      3.1.2

    • getEnumerationForKey

      IEnumeration getEnumerationForKey(String prototypeName, String key, IContextId contextId)
      Returns the instance of the enum factory, that handles the enumeration for a given key.

      Use the dot notation, if the enum is under a structure or collection (e.g. mystructure.substructure).

      This is a shortcut for determining the enum ID and then calling getEnumerationForEnumId(IEnumType, IContextId)

      Parameters:
      key -
      prototypeName -
      Returns:
      the IEnumeration instance created for the specified key
      See Also:

    • getObjectEnumerationForKey

      IObjectEnumeration getObjectEnumerationForKey(String prototypeName, String key, IContextId contextId)
      Returns the instance of the object enum factory, that handles the enumeration for a given key.

      Use the dot notation, if the enum is under a structure or collection (e.g. mystructure.substructure).

      This is a shortcut for determining the enum ID and then calling getObjectEnumerationForEnumId(IEnumType, IContextId)

      Parameters:
      key -
      prototypeName -
      Returns:
      the IObjectEnumeration instance created for the specified key
      Since:
      3.6.3
      See Also:

    • getEnumerationForEnumId

      @NotNull IEnumeration getEnumerationForEnumId(@NotNull IEnumType type, @NotNull IContextId contextId)
      Returns the enumeration for a given enumeration type.
      See Also:

    • getObjectEnumerationForEnumId

      IObjectEnumeration getObjectEnumerationForEnumId(IEnumType type, IContextId contextId)
      Returns the instance of the object enum factory, that handles the enumeration with a given ID.
      Parameters:
      type -
      contextId - - context for factory
      Returns:
      the IObjectEnumeration instance created for the specified enumId
      Since:
      3.6.3

    • getEnumerationObjectFactories

      Map<String,IEnumObjectFactory> getEnumerationObjectFactories()
      Returns a map of all enumeration object factories
      Since:
      3.6.3

    • getConstantEnumerationIds

      @NotNull Set<String> getConstantEnumerationIds()
      Returns a set of constant enumeration IDs. It does NOT contain enumerations that can be modified in Administration.
      Since:
      3.9.0

    • getObjectFromEnumOption

      IPObject getObjectFromEnumOption(IEnumOption enumOption)
      Returns the IPObject instance from the given IEnumOption if it exists.
      Returns:
      the IPObject instance returned for the given enumOption
      Since:
      3.6.3

    • getObjectHistory

      @NotNull <T extends IPObject> IPObjectList<T> getObjectHistory(@NotNull T object)
      Returns the whole history of the a given object, in the form of its versioned objects. The objects in the returned collection are not resolved and the client should be able to handle the situation, when not all objects in the history are resolvable.

      The history list is sorted from the oldest (first) to the newest (last).

      An empty list is returned if the object does not support history retrieval.

      Parameters:
      object -
      Returns:
      a IPObjectList containing all versions of the specified IPObject
      See Also:

    • getVersionedInstance

      @NotNull IPObject getVersionedInstance(SubterraURI uri, String revision)
      Returns a versioned object for the given uri and revision.

      The object may be unresolvable.

      Parameters:
      uri - The URI of a object. Cannot be null.
      revision - If null, then the object without a specific revision will be returned.
      Returns:
      The versioned IPObject implementing the model-specific interface (if registered) or just a generic IPObject if none is specified.

    • getVersionedInstance

      IPObject getVersionedInstance(IObjectId objectId, String revision)
      Returns a versioned object for the given uri and revision.

      The object may be unresolvable.

      Parameters:
      objectId - IObjectId of a object. If null, then an instance without a version will be returned (even if the source objectId has a revision).
      revision - If null, then an object without a specific revision will be returned.
      Returns:
      The versioned IPObject implementing the model-specific interface (if registered) or just a generic IPObject if none is specified.

    • getPrototypeFromObjectURI

      IPrototype getPrototypeFromObjectURI(SubterraURI uri)
      Returns the prototype that the uri of the given object belongs to. For example if its a passed uri of some work item, then it returns the WorkItem prototype.

      Parameters:
      uri -
      Returns:
      the IPrototype of the object at the specified uri

    • getSubterraURIForObjectId

      SubterraURI getSubterraURIForObjectId(IObjectId id)
      Return SubterraURI for given object id. Reverse method to getObjectIdForSubterraURI(SubterraURI)
      Parameters:
      id - object id
      Returns:
      SubterraURI
      Throws:
      IllegalArgumentException - if id is null

    • getObjectIdForSubterraURI

      IObjectId getObjectIdForSubterraURI(SubterraURI uri)
      Reverse method to getSubterraURIForObjectId(IObjectId)
      Parameters:
      uri -
      Returns:
      the IObjectId for the passed uri

    • adapt

      Object adapt(IPObject adaptable, Class targetClass)
      Adapts the given IPObject to the instance of the given target class. Returns null if such an adaptation is not supported.
      Parameters:
      adaptable -
      targetClass -
      Returns:
      adaptable adapted to be an instance of targetClass

    • getSupportedTargetClasses

      Class[] getSupportedTargetClasses(String protoName)
      Even if the adaptation is possible for the given prototype in general, it can still be impossible for a particular instance.
      Parameters:
      protoName -
      Returns:
      An array of types that the instances of the given prototype can be adapted for.
      See Also:

    • getDiffManager

      IDiffManager getDiffManager()

    • getPersistencePolicy

      IPersistencePolicy getPersistencePolicy()

    • getSecurityService

      ISecurityService getSecurityService()
      Shortcut method to get the platform security service.
      Returns:
      the platform security service.

    • getRevision

      IRevision getRevision(IContextId contextId, String revisionId)
      Same as getRevision(String, String), but the repository name is determined from the context.

    • getRevision

      IRevision getRevision(String repositoryName, String revisionId)
      Same as getRevision(IContextId, String), but the revision.
      Parameters:
      repositoryName - The repository that the revision comes from (must NOT be null).
      revisionId - The revision ID (must NOT be null)..
      Returns:
      The unresolved IRevision with a given ID. The operation is performed only with the IDs, so it is not guaranteed that such a revision actually exists and will be resolvable. Never returns null.

    • getLastStorageRevision

      @NotNull IRevision getLastStorageRevision()
      This method should be used instead of IRepositoryReadOnlyConnection.getCurrentRepositoryState() in use cases related to the model objects (i.e. the ones returned by getInstance(IObjectId))
      Returns:
      from the primary storage (i.e. the IRepositoryService.DEFAULT repository) of the model objects the last revision. Ignores the baseline set by doInBaseline(String, RunnableWEx)
      Since:
      3.19.2

    • getStorageRevisionAt

      @NotNull IRevision getStorageRevisionAt(@NotNull Date timePoint)
      This method should be used instead of IRepositoryReadOnlyConnection.getRepositoryState(Date) in use cases related to the model objects (i.e. the ones returned by getInstance(IObjectId))
      Returns:
      from the primary storage of the model objects (i.e. the IRepositoryService.DEFAULT repository) the last revision that was created before or at the given time point.
      Since:
      3.19.2

    • getValidRevisionInBaseline

      @NotNull IRevision getValidRevisionInBaseline(@NotNull String revision)
      Returns:
      the given revision if the getCurrentBaselineRevision() is null or higher than the given revision, otherwise returns the getCurrentBaselineRevision(), in both cases wrapped as an IRevision.
      Throws:
      NumberFormatException - when the given revision cannot be parsed as long number.
      Since:
      3.19.2

    • getPreviousStorageRevision

      @NotNull IRevision getPreviousStorageRevision(@Nullable String revision)
      This method should be used instead of IRepositoryReadOnlyConnection.getPreviousState(String) in use cases related to the model objects (i.e. the ones returned by getInstance(IObjectId))
      Returns:
      from the primary storage (i.e. the IRepositoryService.DEFAULT repository) of the model objects the revision before the given one. Returns 0 when the given one is null or lower than 1.
      Throws:
      NumberFormatException - when the given revision cannot be parsed as long number.
      Since:
      3.19.2

    • objectsChanged

      void objectsChanged(Collection uris)
      Causes the objects with the given uris being refreshed in the cache and index. This method is especially meant for derived fields providers, who should call this method whenever the derived fields change (because of external events) to notify persistence about this change.

      The clients should be aware, that the method is likely to take a long time (depending on the number of uris to process).

      Parameters:
      uris -

    • clearCaches

      void clearCaches()
      Clear all object and document caches in the system. (Works for the whole cluster in cluster setup.)

    • clearCaches

      void clearCaches(Collection<SubterraURI> uris)
      For given uris, clear all object and document caches in the system.
      Since:
      3.2.0

    • clearCaches

      void clearCaches(Collection<SubterraURI> uris, boolean globalOnly)
      For given uris, clear all object and document caches in the system.
      Parameters:
      globalOnly - If true then only the global data object cache is cleared
      Since:
      3.7.0

    • clearCaches

      void clearCaches(@NotNull String nodeId)
      For a given node in a cluster, clear all object and document caches in the system.
      Parameters:
      nodeId - - The node ID of the node to clear its caches.
      Since:
      3.8.0

    • getExternalRepositoryProviderRegistry

      IExternalRepositoryProviderRegistry getExternalRepositoryProviderRegistry()
      Since:
      3.5.1

    • doInBaseline

      <T> T doInBaseline(String baselineRevision, RunnableWEx<T> r)
      Executes code in the given runnable, inside the baseline context.
      Parameters:
      baselineRevision - can not be null or an empty string.
      Throws:
      UserFriendlyRuntimeException - if baselineRevision is not a valid number.
      Since:
      3.6.0

    • doOutsideBaseline

      <T> T doOutsideBaseline(RunnableWEx<T> r)
      Since:
      3.6.0

    • getCurrentBaselineRevision

      String getCurrentBaselineRevision()
      Since:
      3.6.0

    • getLastRevisionCommitedByCurrentThread

      String getLastRevisionCommitedByCurrentThread()
      Since:
      3.6.0

    • refreshEnumerations

      void refreshEnumerations(IContextId contextId)
      Refreshes enumerations (stored in the database) in a given project. If contextId is null, refreshes enumerations in all projects.
      Since:
      3.8.0

    • getInstancesCountInBaseline

      int getInstancesCountInBaseline(@NotNull String index, @NotNull String query, @Nullable String revision)
      Searches the count of objects in the given index from a given revision. In a typical case, the index name corresponds to the prototype name, however, there can be some additional indices defined, that don't correspond to a particular prototype.
      Parameters:
      index -
      query -
      revision - baseline revision, or null not to search in a baseline
      Returns:
      An objects count by a specified query.
      Since:
      3.17.2