Package com.orchestranetworks.instance

# Class Repository

java.lang.Object
com.orchestranetworks.instance.Repository

public abstract class Repository extends Object
Represents the data repository in EBX®.

In EBX®, the data life cycle is organized and managed through dataspaces and snapshots.

Note: Dataspaces and snapshots were collectively referred to as "homes" in previous versions. Individually, dataspaces were called "branches", and snapshots were called "versions". For legacy reasons, naming in the Java API continues to use the terms "home", "branch", and "version". For a complete list of term changes, see Notes to developers.

Their main properties are as follows:

- Dataspaces and snapshots provide views on data that are strictly isolated from one another with respect to the data life cycle;
- In the EBX® repository, dataspaces and snapshots are organized into a single hierarchy whose root is always the reference dataspace.

A dataspace or snapshot is represented by an instance of class `AdaptationHome` .

### Dataspace

"Branch" prior to V5.

Any update to the repository only happens in the context of one dataspace. A dataspace is a set of contents that can be modified by creating new content, or modifying or deleting existing content.

The primary function of a dataspace is isolation: any scoped content in the dataspace is not be impacted by updates outside that dataspace. Conversely, any updates within the dataspace will not affect scoped contents in other dataspaces.

The repository always has a dataspace called `Reference`. Other than the reference dataspace, all dataspaces are created from other dataspaces, called their parent dataspaces. Every dataspace has an initial snapshot, which is automatically created from the parent dataspace. This initial snapshot is used to compute change sets of the dataspace.

See dataspace in the glossary for more information.

### Snapshot

"Version" prior to V5.

A snapshot is a dataspace in the repository whose contents are guaranteed not to change after its creation. That is, no updates can be made to its contents, and it is fully isolated from modifications performed in other dataspace.

A snapshot is always taken based on a dataspace, called its parent dataspace.

See snapshot in the glossary for more information.

### How to get a repository?

When the thread is running inside an EBX® container then its context is on a particular `dataspace or snapshot`. If it needs to access the repository, it must call `AdaptationHome.getRepository()`.

Otherwise, in an external program that does not have access to a current EBX® context (for example a `ProgrammaticService`), the thread must call `getDefaultWhenFullyInitialized()` to get the default fully initialized repository instance.

### Consistency and validation life cycle

In EBX®, committed data is not necessarily required to be in a valid state (see method `Adaptation.getValidationReport()`). The main reasons are:

- Validation depends on the underlying data model. Since it is an external resource whose life cycle is not the same as the data managed in EBX®, it can evolve independently from them, and hence add new errors if constraints become more restrictive.
- A commit policy that blocks commits in case of validation errors can lead to difficult use cases because, in practice, data must be allowed to be in temporarily inconsistent states. For example for deleting self-referencing objects or for handling an import whose data needs some cleaning.

For all use cases where a client requires a stable and consistent view (for example, to export data from EBX® to a third-party system), it is mandatory:

1. to execute the whole client code in the SERIALIZABLE isolation level (see Concurrency and isolation levels);
2. to ensure that the view is consistent, by calling `Adaptation.isSchemaDefinitionCompliant(boolean)` (or `Adaptation.getValidationReport()`);
3. then to call the client code that requires a stable and consistent view (for example a data export);

See Also:
  - `AdaptationHome`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final BranchKey`
  `REFERENCE`
  Identifies the reference dataspace.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `abstract void`
  `closeHome(AdaptationHome aDataSpaceOrSnapshot, Session aSession)`
  Closes the specified dataspace or snapshot.
  `abstract AdaptationHome`
  `createHome(AdaptationHome parentDataSpace, HomeKey aKey, Profile owner, Session aSession, UserMessage aLabel, UserMessage aDescription)`
  Creates the specified dataspace or snapshot.
  `abstract AdaptationHome`
  `createHome(HomeCreationSpec aSpec, Session aSession)`
  Performs the dataspace or snapshot creation as specified.
  `abstract Session`
  `createSessionFromArray(Object[] args)`
  Instantiates a session from an open array.
  `abstract Session`
  `createSessionFromHttpRequest(HttpServletRequest httpServletRequest)`
  Instantiates a session from an HTTP request.
  `abstract Session`
  `createSessionFromLoginPassword(String login, String password)`
  Instantiates a session based on the login and password specified.
  `abstract Session`
  `createSessionFromSOAPHeader(Element header)`
  Instantiates a session from a SOAP Header.
  `abstract SessionPermissions`
  `createSessionPermissionsForUser(UserReference aUserReference)`
  Instantiates a permissions evaluator for the specified user without creating a specific session.
  `abstract void`
  `deleteHome(AdaptationHome aDataSpaceOrSnapshot, Session aSession)`
  Permanently deletes the specified dataspace or snapshot and all its descendants (dataspaces and snapshots).
  `abstract DatabaseMapping`
  `getDatabaseMapping()`
  Returns the delegate for interacting with the names of database tables and columns.
  `abstract RepositoryDeclaration`
  `getDeclaration()`
  Returns general management information on this repository.
  `static Repository`
  `getDefault()`
  Returns the default instance of this class.
  `abstract Locale`
  `getDefaultLocale()`
  Returns the EBX® default locale.
  `static Repository`
  `getDefaultWhenFullyInitialized()`
  Returns the default instance of this class once the full initialization is done.
  `abstract List<Locale>`
  `getLocales()`
  Returns the EBX® declared locales.
  `abstract RepositoryPurge`
  `getPurgeDelegate()`
  Returns the delegate for purge.
  `abstract AdaptationHome`
  `getReferenceBranch()`
  Returns the reference dataspace.
  `abstract RepositoryStatus`
  `getStatus()`
  Returns the delegate for status regarding database ownership.
  `abstract AdaptationHome`
  `lookupHome(boolean d3Lookup, HomeKey aKey)`
  Returns the specified dataspace or snapshot.
  `abstract AdaptationHome`
  `lookupHome(HomeKey aKey)`
  Returns the specified dataspace or snapshot.
  `abstract void`
  `markHomeForPurge(AdaptationHome aDataSpaceOrSnapshot, Session aSession)`
  Deprecated.
  Replaced by `deleteHome(AdaptationHome, Session)`.
  `abstract RepositoryAnonymizer`
  `newAnonymizer()`
  Returns a new delegate to be invoked for anonymization.
  `abstract void`
  `purgeHomes(Session aSession)`
  Deprecated.
  Replaced by `purgeAll`.
  `abstract List<SchemaLocation>`
  `refreshSchemas(boolean isFullRefresh)`
  Refreshes data models and their associated contents loaded in the cache.
  `abstract void`
  `reopenHome(AdaptationHome aHome, Session aSession)`
  Reopens the specified home.
  `abstract void`
  `setDocumentationDescription(AdaptationHome aDataSpaceOrSnapshot, String aDescription, Locale aLocale, Session aSession)`
  Sets the documentation label for the specified dataspace or snapshot.
  `abstract void`
  `setDocumentationLabel(AdaptationHome aDataSpaceOrSnapshot, String aLabel, Locale aLocale, Session aSession)`
  Sets the documentation label for the specified dataspace or snapshot.
  `abstract String`
  `toStringInfo()`

  ### Methods inherited from class java.lang.Object

  `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- ## Field Details

  - ### REFERENCE

    public static final BranchKey REFERENCE
    Identifies the reference dataspace.
    See Also:
      - `getReferenceBranch()`

- ## Method Details

  - ### getDefault

    public static Repository getDefault()
    Returns the default instance of this class. This method is the entry point for accessing data when the thread is not running within EBX®.

    If the thread is running within an EBX® container, it is strongly recommended that you access the current repository from the provided context.

    Throws:
      `RuntimeException` - when the repository is started for maintenance.
    See Also:
      - `getDefaultWhenFullyInitialized()`

  - ### getDefaultWhenFullyInitialized

    public static Repository getDefaultWhenFullyInitialized()
    Returns the default instance of this class once the full initialization is done.

    Note: This method blocks the calling thread until the repository is fully initialized, including modules registration. From that moment, it is able to handle SOAP, REST and UI requests.

    Throws:
      `RuntimeException` - when the repository is started for maintenance.
    Since:
      6.0.12
    See Also:
      - `ModuleRegistration.handleRepositoryStartup(ModuleContextOnRepositoryStartup)`

  - ### getReferenceBranch

    public abstract AdaptationHome getReferenceBranch()
    Returns the reference dataspace.

    The reference dataspace is always defined in the repository and it has no parent dataspace.

    This method is equivalent to `lookupHome(Repository.REFERENCE)`.

  - ### lookupHome

    public abstract AdaptationHome lookupHome(HomeKey aKey)
    Returns the specified dataspace or snapshot. Returns `null` if the specified dataspace or snapshot does not exist.
    See Also:
      - `lookupHome(boolean, HomeKey)`

  - ### lookupHome

    public abstract AdaptationHome lookupHome(boolean d3Lookup, HomeKey aKey)
    Returns the specified dataspace or snapshot. For a D3 replica delivery dataspace, always returns a redirection to the last broadcasted snapshot.

    If `d3Lookup` is `true`:

    - Returns the last broadcasted snapshot if the specified dataspace or snapshot is a delivery dataspace and D3 is activated; if the delivery dataspace has not yet been broadcast, returns its initial snapshot.
    - Returns the specified dataspace or snapshot if it is not a delivery dataspace or if D3 is not activated.
    - Returns `null` if the specified dataspace or snapshot does not exist.

    If `d3Lookup` is `false`:

    - On a replica delivery dataspace, redirection is always activated, then `d3Lookup` parameter is ignored.
    - Otherwise, this method is equivalent to `lookupHome(HomeKey)`.

  - ### reopenHome

    public abstract void reopenHome(AdaptationHome aHome, Session aSession) throws OperationException
    Reopens the specified home.

    If the home is a branch, then this method also reopens its initial version.

    Note: this method cannot be called inside a procedure execution (because of transaction management restrictions).
    Parameters:
      `aHome` - home to reopen.
      `aSession` - session that performs the reopening; the associated user must be allowed to perform the operation.
    Throws:
      `IllegalArgumentException` - if `aHome` is `null`.
      `OperationException` - thrown if operation cannot complete.
    Since:
      6.0.0

  - ### createHome

    public abstract AdaptationHome createHome(HomeCreationSpec aSpec, Session aSession) throws OperationException
    Performs the dataspace or snapshot creation as specified.

    Note: This method cannot be called inside a procedure execution (because of transaction management restrictions).

    Parameters:
      `aSpec` - specifies the dataspace or snapshot to be created.
      `aSession` - the session that performs the creation, it must have the permissions required for this operation.
    Returns:
      the new dataspace or snapshot
    Throws:
      `OperationException` - thrown if creation cannot complete (for example, home identifier already exists, session does not have permission to create the dataspace or snapshot, this method is called inside a procedure execution, etc.).

  - ### createHome

    public abstract AdaptationHome createHome(AdaptationHome parentDataSpace, HomeKey aKey, Profile owner, Session aSession, UserMessage aLabel, UserMessage aDescription) throws OperationException
    Creates the specified dataspace or snapshot.

    Note:

    1. This method cannot be called inside a procedure execution (because of transaction management restrictions).
    2. The preferred and more flexible method for creating a dataspace or snapshot is `createHome(HomeCreationSpec, Session)`.
    Parameters:
      `parentDataSpace` - dataspace from which the new dataspace or snapshot will be created.
      `aKey` - specifies the identifier of the new dataspace or snapshot.
      `owner` - specifies the owner of the new dataspace or snapshot.
      `aSession` - the session that performs the creation.
      `aLabel` - specifies the label of the new dataspace or snapshot, `null` is accepted.
      `aDescription` - specifies the description of the new dataspace or snapshot, `null` is accepted.
    Throws:
      `IllegalArgumentException` - if aKey does not conform to `HomeKey.MAX_KEY_LENGTH` and `HomeKey.KEY_PATTERN`.
      `OperationException` - thrown if creation cannot complete (for example, `parentBranch` is a snapshot, dataspace or snapshot identifier already exists,session does not have permission to create the dataspace or snapshot, this method is called inside a procedure execution, etc.).
    See Also:
      - `createHome(HomeCreationSpec, Session)`

  - ### setDocumentationLabel

    public abstract void setDocumentationLabel(AdaptationHome aDataSpaceOrSnapshot, String aLabel, Locale aLocale, Session aSession) throws OperationException
    Sets the documentation label for the specified dataspace or snapshot.

    Note: This method cannot be called inside a procedure execution (because of transaction management restrictions).

    Parameters:
      `aDataSpaceOrSnapshot` - the dataspace or snapshot on which the label is to be changed.
      `aLabel` - new label for the dataspace or snapshot.
      `aLocale` - the locale of the label.
      `aSession` - the session that performs the documentation change.
    Throws:
      `IllegalArgumentException` - if `aDataSpaceOrSnapshot` or `locale` are `null`.
      `OperationException` - thrown if operation cannot complete.

  - ### setDocumentationDescription

    public abstract void setDocumentationDescription(AdaptationHome aDataSpaceOrSnapshot, String aDescription, Locale aLocale, Session aSession) throws OperationException
    Sets the documentation label for the specified dataspace or snapshot.

    Note: This method cannot be called inside a procedure execution (because of transaction management restrictions).

    Parameters:
      `aDataSpaceOrSnapshot` - the dataspace or snapshot on which the label must be changed.
      `aDescription` - new description for the dataspace or snapshot.
      `aLocale` - locale of the label.
      `aSession` - the session that performs the documentation change.
    Throws:
      `IllegalArgumentException` - if `aDataSpaceOrSnapshot` or `locale` are `null`.
      `OperationException` - thrown if operation cannot complete.

  - ### closeHome

    public abstract void closeHome(AdaptationHome aDataSpaceOrSnapshot, Session aSession) throws OperationException
    Closes the specified dataspace or snapshot.

    Once a dataspace or snapshot has been closed, it cannot be viewed by normal users. However, its content is not removed from repository.

    Note: This method cannot be called inside a procedure execution (because of transaction management restrictions).
    Parameters:
      `aDataSpaceOrSnapshot` - the dataspace or snapshot to be closed.
      `aSession` - the session that performs the closure; the associated user must be allowed to perform the operation.
    Throws:
      `IllegalArgumentException` - if `aDataSpaceOrSnapshot` is `null`.
      `OperationException` - thrown if operation cannot complete.
      `ConstraintViolationException` - If the specified dataspace or snapshot is being referenced by a foreign key constraint (`osd:tableRef`) in blocking mode.

  - ### createSessionFromLoginPassword

    public abstract Session createSessionFromLoginPassword(String login, String password) throws AuthenticationException
    Instantiates a session based on the login and password specified.

    This method calls method `Directory.authenticateUserFromLoginPassword(String, String)`.

    Returns:
      a session with the user corresponding to the specified parameters, or `null` if login does not exist or password is incorrect.
    Throws:
      `AuthenticationException` - if authentication fails for a reason that is more specific than an unknown login or an incorrect password (for example a security violation or a physical access failure).

  - ### createSessionFromHttpRequest

    public abstract Session createSessionFromHttpRequest(HttpServletRequest httpServletRequest) throws AuthenticationException
    Instantiates a session from an HTTP request.

    This method calls method `Directory.authenticateUserFromHttpRequest(HttpServletRequest httpServletRequest)`.

    Returns:
      a session with the user authenticated by the specified servlet, or `null` if authentication features are not provided in the request.
    Throws:
      `AuthenticationException` - if authentication cannot complete.

  - ### createSessionFromSOAPHeader

    public abstract Session createSessionFromSOAPHeader(Element header) throws AuthenticationException
    Instantiates a session from a SOAP Header.

    This method calls method `Directory.authenticateUserFromSOAPHeader(Element)`.

    Returns:
      a session with the user authenticated by the specified SOAP header, or `null` if authentication features are not provided in the request.
    Throws:
      `AuthenticationException` - if authentication cannot complete.

  - ### createSessionFromArray

    public abstract Session createSessionFromArray(Object[] args)
    Instantiates a session from an open array.

    This method calls method `Directory.authenticateUserFromArray(Object[])`.

    Returns:
      a session with the user corresponding to the specified parameter, or `null` if no user can be authenticated.

  - ### createSessionPermissionsForUser

    public abstract SessionPermissions createSessionPermissionsForUser(UserReference aUserReference)
    Instantiates a permissions evaluator for the specified user without creating a specific session.
    Since:
      5.4.1

  - ### getDeclaration

    public abstract RepositoryDeclaration getDeclaration()
    Returns general management information on this repository.

  - ### getPurgeDelegate

    public abstract RepositoryPurge getPurgeDelegate()
    Returns the delegate for purge.

  - ### getDatabaseMapping

    public abstract DatabaseMapping getDatabaseMapping()
    Returns the delegate for interacting with the names of database tables and columns.

  - ### newAnonymizer

    public abstract RepositoryAnonymizer newAnonymizer()
    Returns a new delegate to be invoked for anonymization.

  - ### getDefaultLocale

    public abstract Locale getDefaultLocale()
    Returns the EBX® default locale.
    Since:
      5.9.0
    See Also:
      - Configuring EBX® localization

  - ### getLocales

    public abstract List<Locale> getLocales()
    Returns the EBX® declared locales.
    Since:
      5.9.0
    See Also:
      - Configuring EBX® localization

  - ### markHomeForPurge

    @Deprecated public abstract void markHomeForPurge(AdaptationHome aDataSpaceOrSnapshot, Session aSession) throws OperationException
    Deprecated.
    Replaced by `deleteHome(AdaptationHome, Session)`.
    Throws:
      `OperationException`

  - ### deleteHome

    public abstract void deleteHome(AdaptationHome aDataSpaceOrSnapshot, Session aSession) throws OperationException
    Permanently deletes the specified dataspace or snapshot and all its descendants (dataspaces and snapshots). Only the data of a closed dataspace or snapshot is concerned by this request (if the closed dataspace or snapshot has history, it must be marked separately for purge using the method `markHomeForHistoryPurge`).

    This deletion is definitive, but does not perform a complete physical purge. The actual purge is not performed until a purge execution is requested (see method `purgeAll`). Deleting a dataspace or snapshot also deletes all its descendants (that is, all child dataspaces and snapshots, recursively); if a dataspace is specified, its initial snapshot is also deleted.

    Parameters:
      `aDataSpaceOrSnapshot` - the dataspace or snapshot to delete; all descendants are also deleted.
      `aSession` - the session that performs the operation; the associated user must be `administrator`.
    Throws:
      `OperationException` - thrown if operation cannot complete (for example, if a dataspace or snapshot is not closed).
    See Also:
      - `RepositoryPurge.purgeAll(Session)`
      - `getPurgeDelegate()`

  - ### purgeHomes

    @Deprecated public abstract void purgeHomes(Session aSession) throws OperationException
    Deprecated.
    Replaced by `purgeAll`.
    Performs a complete deletion of the physical entities that have been partially deleted or marked for purge.
    Throws:
      `OperationException`

  - ### getStatus

    public abstract RepositoryStatus getStatus()
    Returns the delegate for status regarding database ownership.

  - ### refreshSchemas

    public abstract List<SchemaLocation> refreshSchemas(boolean isFullRefresh)
    Refreshes data models and their associated contents loaded in the cache.
    Parameters:
      `isFullRefresh` - if `true`, all known data models are invalidated, if `false` only data models which have been updated since their last loading are invalidated.
    Returns:
      a list of `SchemaLocation`, the data models that have actually been refreshed.
    Throws:
      `IllegalStateException` - if the thread invoking this method is running a `Procedure` (or an `InstanceTrigger` or `TableTrigger`); data model refresh must be done outside any transaction to preserve data consistency.

  - ### toStringInfo

    public abstract String toStringInfo()