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:

  • Field Details

  • 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

      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:

    • 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

      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:

    • 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:

    • getLocales

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

    • 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:

    • 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()