Package ch.ivyteam.ivy.business.data.store

Interface BusinessDataRepository

public interface BusinessDataRepository

Entry point for the Business Data feature.
Business data values can be stored and loaded from the repository.
Business data values are typically data classes or Java objects.

It's recommended to annotate the business data with BusinessCaseData. In this case the business data object will be automatically connected to the business case. Otherwise you have to store the id of the business case data in the process data to receive the corresponding business data later on.

Gives access to basic operations like save(Object), find(String, Class) and delete(Object)

Example:

  Dossier dossier = ... // an ivy data class annotated with BusinessCaseData
  ivy.repo.save(dossier);

  Dossier storedDossier = ivy.repo.get(Dossier.class) as Dossier;
  storedDossier.getPerson().setFirstName("Marco");
  ivy.repo.save(storedDossier);

  ivy.repo.getInfo(storedDossier).getVersion(); // is 2
 
  // If your business data is not annotated with BusinessCaseData you must manually save the id
  in.businessDataId = ivy.repo.getId(dossier);
  Dossier storedDossier = ivy.repo.find(in.businessDataId, Dossier.class) as Dossier;

Identity

A unique id is generated if a Business Data value is stored the first time.
If there is a field with the name id in the Business Data class, the generated id will be stored into this field.

Example:

  Dossier dossier = ... // an ivy data class, the id field is null
  ivy.repo.save(dossier);
  dossier.id // is the generated id

Own Identifier

To use your own id set the id before saving your Business Data value for the first time.
Be aware that the id can not be changed later and the maximum length of the identifier is 100 characters.

Example:

  Dossier dossier = ... // an ivy data class
  String yourId = ... // generate your own id, be sure it is unique!
  dosser.id = yourId; // set your id the Business Data value
  ivy.repo.save(dossier);
  dossier.id // is your id

  ivy.repo.find(yourId, Dossier.class) // get your Business Data value

Warning

You should only store the id of a Business Data value in the process data and not the value itself.

After a Task Switch you must reload the Business Data value from the repo with the stored id.
This is required, because the Business Data repo does not keep the reference to the Business Data value instance on a Task Switch.

Since:
6.3.0
API:
This is a public API.

  • Method Summary

    Modifier and Type
    Method
    Description
    static BusinessDataRepository
    current()
    Gets the current business data repository.
    <T> void
    delete(T value)
    Deletes the given business data value in the repository.
    void
    deleteById(String id)
    Deletes the business data value with the given id in the repository.
    <T> boolean
    exists(Class<T> type)
    Checks for existence of a business case data value in the repository.
    boolean
    exists(String id)
    Checks for existence of a business data value in the repository.
    <T> T
    find(IBusinessCase businessCase, Class<T> type)
    Retrieves a business data value from a given business case.
    <T> T
    find(String id, Class<T> type)
    Retrieves a business data value by its id and type.
    <T> T
    get(Class<T> type)
    Retrieves a business case data value by its type.
    <T> String
    getId(T value)
    Get the id of a given business data value.
    <T> BusinessDataInfo<T>
    getInfo(T value)
    Retrieves the information about the given business data value.
    <T> BusinessDataInfoRepository<T>
    infos(Class<T> type)
    Gets the business data info repository that allows to iterate over stored business data infos.
    <T> boolean
    isUpToDate(T value)
    Checks if the given business data value is up-to-date.
    <T> BusinessDataInfo<T>
    overwrite(T value)
    Inserts or overwrites the given business data value regardless of the version.
    <T> T
    overwrite(T value, String field)
    Overwrites only the specified field of the given business data value.
    Concurrently updated values of other fields by other participants are preserved.
    <T> T
    reload(T value)
    Reloads the given business data value from the repository.
    <T> BusinessDataInfo<T>
    save(T value)
    Inserts or updates the given business data value with respect to the version (optimistic locking).
    <T> Query<T>
    search(Class<T> type)
    Search for business data using different filters for text, number and date fields.

  • Method Details

    • current

      static BusinessDataRepository current()

      Gets the current business data repository.

      Will return null if called out of scope. The scope is set if you call this method from an ivy process or any supported ivy environment. It is not set in non supported ivy environments (e.g. if you start your own threads, etc.).

      Returns:
      current case map service or null if out of scope
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • getId

      <T> String getId(T value)

      Get the id of a given business data value.

      The maximum length of the identifier is 100 characters.

      Parameters:
      value - business data value
      Returns:
      the id of the business data value or null if it does not or no longer exist
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • getInfo

      <T> BusinessDataInfo<T> getInfo(T value)
      Retrieves the information about the given business data value.

      Example:

        import ch.ivyteam.ivy.business.data.store.BusinessDataInfo;

  Dossier dossier = ...

  BusinessDataInfo<Dossier> businessDataInfo = ivy.repo.getInfo(dossier);
  businessDataInfo.getId();
      Parameters:
      value - the initial value
      Returns:
      the BusinessDataInfo for the given value or null if it does not or no longer exist
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • get

      <T> T get(Class<T> type)
      Retrieves a business case data value by its type.

      Example: Get (load or create), modify and save a Dossier value in the context of the current business case:

       BusinessCaseDossier dossier = ivy.repo.get(BusinessCaseDossier.class);
 dossier.getPerson().setLastName("Polo");
 ivy.repo.save(dossier);

      Use find(IBusinessCase, Class) to get the business data of another business case.

      Parameters:
      type - must be annotated with the BusinessCaseData annotation.
      Returns:
      Business data value or a new instance associated with the current business case.
      Throws:
      IllegalArgumentException - if type has no BusinessCaseData annotation.
      Since:
      6.6
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • find

      <T> T find(String id, Class<T> type)
      Retrieves a business data value by its id and type.
      Parameters:
      id -
      type -
      Returns:
      Business data value or null if it does not exist
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • find

      <T> T find(IBusinessCase businessCase, Class<T> type)
      Retrieves a business data value from a given business case.

      Example:

        import ch.ivyteam.ivy.workflow.businesscase.IBusinessCase;

  IBusinessCase businessCase = ivy.wf.findCase(23).getBusinessCase();

  BusinessCaseDossier dossier = ivy.repo.find(businessCase, BusinessCaseDossier.class);

      Use get() to get the business data of the current business case.

      Parameters:
      businessCase -
      type -
      Returns:
      Business data value or null if it does not exist
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • exists

      <T> boolean exists(Class<T> type)
      Checks for existence of a business case data value in the repository.
      Parameters:
      type - must be annotated with the BusinessCaseData annotation.
      Returns:
      true if exists
      Throws:
      IllegalArgumentException - if type has no BusinessCaseData annotation.
      Since:
      6.6
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • exists

      boolean exists(String id)
      Checks for existence of a business data value in the repository.
      Parameters:
      id -
      Returns:
      true if exists
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • search

      <T> Query<T> search(Class<T> type)

      Search for business data using different filters for text, number and date fields. The result can be ordered and limited.

      Limitation: Takes up to one second after a create, update, delete until results are searchable.

      Example:

       import workflow.business.data.Dossier;

 List<Dossier> result = ivy.repo.search(Dossier.class)
      .textField("person.firstName").containsWordPattern("A*")
      .orderBy().field("person.lastName").descending()
      .limit(10)
      .execute()
      .getAll();

      Allows to build Google like searches with Query.score(). The returned result hits are by default ordered by score (best fit first). Note, some result may not match the complete query string but may also be relevant.

      Example:

       import workflow.business.data.Dossier;

 List<Dossier> result = ivy.repo.search(Dossier.class)
      .score().allTextFields().query("Axon+Ivy~1")
      .limit(50)
      .execute()
      .getAll();
      This will return all dossiers that contain the words Axon and Ivy but also dossiers where Ivy is not spelled correct (e.g. Ivi, Ify, etc).

      Filters and score can be combined.

      By default the search result is limited to 10 entries. If you don't specify a limit explicit with Limit.limit(int) you will only get the first 10 results back.

      Parameters:
      type - the business data type
      Returns:
      query operations
      API:
      This public API is available in IvyScript and Java. It has the visibility ADVANCED.

    • save

      <T> BusinessDataInfo<T> save(T value)

      Inserts or updates the given business data value with respect to the version (optimistic locking).

      Use isUpToDate(Object) to check if the given value has the latest version.

      If the value was modified and saved concurrently by another participant since this business data value was loaded, then this method throws a ConcurrentModificationException exception.
      In this case:

      • Reload the business data value and re-modify it's value and then try to save(Object) it again.
      • If only a part of the value was modified it's possible to overwrite only a part with update(Object, BusinessDataUpdater) or overwrite(Object, String).
      • Use overwrite(Object) to save regardless of other changes.

      Example:

        Dossier dossier = ... // an ivy data class
  dossier.getPerson().setFirstName("Marco");
  String id = ivy.repo.save(dossier).getId();
      Parameters:
      value - the object to save
      Returns:
      the BusinessDataInfo of the saved value
      Throws:
      ConcurrentModificationException - if the business data value was changed/deleted concurrently (by an other participant) since it was loaded
      IllegalArgumentException - thrown if the business data value could not be serialized (only in the designer)
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • overwrite

      <T> BusinessDataInfo<T> overwrite(T value)
      Inserts or overwrites the given business data value regardless of the version.

      Can lead to data loss if the value was modified and stored by another participant since loading the business data value.

      Parameters:
      value - the business data value to overwrite
      Returns:
      the BusinessDataInfo of the overwritten value
      Throws:
      IllegalArgumentException - thrown if the business data value could not be serialized (only in the designer)
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • overwrite

      <T> T overwrite(T value, String field)

      Overwrites only the specified field of the given business data value.
      Concurrently updated values of other fields by other participants are preserved. After the operation returned business data value contains the changes of all participants.

      Allows to partially update a business data value (e.g. when different participants work on the same business data).

      Warning: Can lead to inconsistency when not carefully used.

      Developer notes:

      • The resolution of the field is executed by the ivy script engine.
      • Throws an exception if the business data value was not stored.
      • After updating the business data value, it is reloaded from the repository and returned.
      • It is recommended to use the returned, updated business data value for further operations.
      • Overwrites changes from other participants on the same field.

      Example:

       Dossier dossier = ...;

 ivy.repo.save(dossier); // version = 1

 Dossier otherParticipantDossier = ivy.repo.find(ivy.repo.getId(dossier), Dossier.class) as Dossier;
 otherParticipantDossier.setName("Other Name");
 ivy.repo.save(otherParticipantDossier);  // version = 2

 dossier.getPerson().setFirstName("Anna");
 Dossier updated = ivy.repo.overwrite(dossier, "person.firstName"); // version = 3

 updated.getName(); // is "Other Name"
 updated.getPerson().getFirstName(); // is "Anna"
      Parameters:
      value - the business data value to update
      field - the field to update (e.g "person.firstName")
      Returns:
      the updated business data value
      Throws:
      ConcurrentModificationException - if the business data value was deleted concurrently (by another participant) since it was loaded
      IllegalArgumentException - if the field does not exists or the field value could not be assigned or could not be serialized
      See Also:
      • update(Object, BusinessDataUpdater)
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.

    • delete

      <T> void delete(T value)

      Deletes the given business data value in the repository.

      Does not check if version is up to date. Does nothing if the business data was already deleted.

      Parameters:
      value - the business data value to delete
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • deleteById

      void deleteById(String id)

      Deletes the business data value with the given id in the repository.

      Does not check if version is up to date. Does nothing if the business data was already deleted.

      Parameters:
      id -
      Since:
      7.2
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • isUpToDate

      <T> boolean isUpToDate(T value)

      Checks if the given business data value is up-to-date.

      Parameters:
      value - the business data to check if is updated
      Returns:
      true if the current version is the same as in the repository
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • reload

      <T> T reload(T value)

      Reloads the given business data value from the repository.

      After reloading the business data value you have to work with returned object.
      Parameters:
      value - the business data value to reload
      Returns:
      the reloaded business data value
      Throws:
      NoSuchElementException - if the given value does not exist in the repository
      ConcurrentModificationException - if the business data value was deleted in the meantime by an other participant.
      See Also:
      API:
      This public API is available in IvyScript and Java. It has the visibility NOVICE.

    • infos

      <T> BusinessDataInfoRepository<T> infos(Class<T> type)

      Gets the business data info repository that allows to iterate over stored business data infos.

      Parameters:
      type - the business data type
      Returns:
      repository to access BusinessDataInfo
      Since:
      10.0.2
      API:
      This public API is available in IvyScript and Java. It has the visibility EXPERT.