com.orchestranetworks.instance
Class Repository

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

public abstract class Repository

extends Object

Represents a particular EBX.Platform repository.

In EBX.Platform, Master Data life cycle is organized and managed through branches and versions. Branches and versions are also called homes, their main properties are the following:

• each home provides a view on Master Data that is strictly isolated from other homes regarding data life cycle;
• in the whole repository, homes are organized in a single hierarchy whose root and initial home is Reference branch.

A home is represented by an instance of class AdaptationHome .

Branch

Any update on the repository may only happen in the context of one branch. Hence a branch is a set of contents that may be modified: existing content may be modified or deleted, new content may be created.

The main feature that a branch provides is isolation: any scoped content in the branch will not be impacted by updates outside this branch, and reversely any updates inside the branch will not modify scoped contents in other branches.

The repository has always at least a branch called Reference. Except Reference branch, any branch is created from another branch, it is called its parent branch. It has also always an initial version which is automatically created from the parent branch (this version is needed for computing the change set of the branch).

Version

A version is a snapshot of a repository. Its content has the guarantee to remain unchanged : that is, no update can occur inside it and it is fully isolated from modifications done in other branches.

A branch is always created from a branch, it is called its parent branch.

How to get a repository?

When the thread is running inside an EBX.Platform container, or with a ServiceContext, then its context is on a particular home. If it needs to access to the repository, it must call AdaptationHome.getRepository().

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

Concurrency and isolation levels

In EBX.Platform, three execution modes guarantee a fully committed view on data, an isolation level that is equivalent to SERIALIZABLE (the highest isolation level in ANSI/ISO SQL):

1. if client code is run inside a Procedure container;
2. if client code accesses to a branch that has been explicitly locked (see class LockSpec);
3. if client code accesses to a version.

Outside these execution modes, isolation level corresponds to "READ UNCOMMITTED". This low isolation level implies that the client code can perform "dirty reads"; for example an occurrence can be modified (or created or deleted) by a concurrent thread and this modification (respectively creation, deletion) is possibly viewed by the client code.

Consistency and validation life cycle

In EBX.Platform, committed data are not required by nature to be consistent regarding their validation state (see method Adaptation.getValidationReport()). The main reasons are:

• Validation depends on the underlying XML schema. Since it is an external resource whose life cycle is not the same as Master Data, it can evolve independently of them and hence add new errors if constraints become more restrictive.
• A commit policy that would block commit in case of validation errors can lead to difficult use cases, because in practice data has to become temporarily inconsistent. 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, for exporting Master Data to a third-party system), it is mandatory:

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

See Also:

AdaptationHome

Field Summary

static BranchKey

REFERENCE Identifies the Reference Branch.

Method Summary

abstract void	closeHome(AdaptationHome aHome, Session aSession) Closes the home specified.
abstract AdaptationHome	createHome(AdaptationHome parentBranch, HomeKey aKey, Profile owner, Session aSession, UserMessage aLabel, UserMessage aDescription) Creates the home 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 from the login and password specified.
abstract RepositoryDeclaration	getDeclaration() Returns general management information on this repository.
static Repository	getDefault() Returns the default instance of this class.
abstract AdaptationHome	getReferenceBranch() Returns the Reference Branch.
abstract void	lock(AdaptationHome aBranch, boolean lockParentBranch, Session aSession) Deprecated. Replaced by LockSpec.lock(AdaptationHome, Session)
abstract void	lock(AdaptationHome aBranch, boolean lockParentBranch, String aComment, Session aSession) Deprecated. Replaced by LockSpec.lock(AdaptationHome, Session)
abstract AdaptationHome	lookupHome(HomeKey aKey) Returns the home specified.
abstract void	markHomeForPurge(AdaptationHome aHome, Session aSession) Marks the home specified for purge.
abstract void	purgeHomes(Session aSession) Purges the homes that have been marked for purge.
abstract List	refreshSchemas(boolean isFullRefresh) Refreshes schemas and their associated contents loaded in the cache.
abstract void	setDocumentationDescription(AdaptationHome aHome, String aDescription, Locale aLocale, Session aSession) Sets the documentation label for the home specified.
abstract void	setDocumentationLabel(AdaptationHome aHome, String aLabel, Locale aLocale, Session aSession) Sets the documentation label for the home specified.
abstract String	toStringInfo()
abstract void	unlock(AdaptationHome aBranch, boolean unlockParentBranch, Session aSession) Deprecated. Replaced by LockSpec.unlock(AdaptationHome, Session)

Methods inherited from class java.lang.Object

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

Field Detail

REFERENCE

public static final BranchKey REFERENCE

Identifies the Reference Branch.

See Also:

getReferenceBranch()

Method Detail

getDefault

public static Repository getDefault()

Returns the default instance of this class. This method is the entry point for accessing Master Data when the thread is not running inside an EBX.Platform container.

getReferenceBranch

public abstract AdaptationHome getReferenceBranch()

Returns the Reference Branch.

The Reference Branch is always defined and it has no parent.

A call to this method is the same as lookupHome(Repository.REFERENCE).

lookupHome

public abstract AdaptationHome lookupHome(HomeKey aKey)

Returns the home specified. Returns null if the home specified does not exist.

createHome

public abstract AdaptationHome createHome(AdaptationHome parentBranch,
                                          HomeKey aKey,
                                          Profile owner,
                                          Session aSession,
                                          UserMessage aLabel,
                                          UserMessage aDescription)
                                   throws OperationException

Creates the home specified.

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

Parameters:

parentBranch - branch from which the new home will be created.

aKey - specifies the identifier of the new home.

owner - specifies the owner of the new home.

aSession - session that performs the creation.

aLabel - specifies the label of the new home, null is accepted.

aDescription - specifies the description of the new home, 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 version, home identifier already exists, session has not the permission to create the home, this method is called inside a procedure execution, etc.).

lock

public abstract void lock(AdaptationHome aBranch,
                          boolean lockParentBranch,
                          Session aSession)
                   throws OperationException

Deprecated. Replaced by LockSpec.lock(AdaptationHome, Session)

Throws:

OperationException

lock

public abstract void lock(AdaptationHome aBranch,
                          boolean lockParentBranch,
                          String aComment,
                          Session aSession)
                   throws OperationException

Deprecated. Replaced by LockSpec.lock(AdaptationHome, Session)

Throws:

OperationException

unlock

public abstract void unlock(AdaptationHome aBranch,
                            boolean unlockParentBranch,
                            Session aSession)
                     throws OperationException

Deprecated. Replaced by LockSpec.unlock(AdaptationHome, Session)

Throws:

OperationException

setDocumentationLabel

public abstract void setDocumentationLabel(AdaptationHome aHome,
                                           String aLabel,
                                           Locale aLocale,
                                           Session aSession)
                                    throws OperationException

Sets the documentation label for the home specified.

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

Parameters:

aHome - home on which the label must be changed.

aLabel - new label for the home.

aLocale - locale of the label. Note : only Locale("fr","FR") and Locale("en,"US") are supported for a display via the Manager

aSession - session that performs the documentation change.

Throws:

IllegalArgumentException - if aHome or locale are null.

OperationException - thrown if operation cannot complete.

setDocumentationDescription

public abstract void setDocumentationDescription(AdaptationHome aHome,
                                                 String aDescription,
                                                 Locale aLocale,
                                                 Session aSession)
                                          throws OperationException

Sets the documentation label for the home specified.

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

Parameters:

aHome - home on which the label must be changed.

aDescription - new description for the home.

aLocale - locale of the label. Note : only Locale("fr","FR") and Locale("en,"US") are supported for a display via the manager

aSession - session that performs the documentation change.

Throws:

IllegalArgumentException - if aHome or locale are null.

OperationException - thrown if operation cannot complete.

closeHome

public abstract void closeHome(AdaptationHome aHome,
                               Session aSession)
                        throws OperationException

Closes the home specified.

Once a home 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:

aHome - home to close.

aSession - session that performs the close, associated user must be allowed to perform the operation.

Throws:

IllegalArgumentException - if aHome is null.

OperationException - thrown if operation cannot complete.

createSessionFromLoginPassword

public abstract Session createSessionFromLoginPassword(String login,
                                                       String password)
                                                throws AuthenticationException

Instantiates a session from the login and password specified.

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

Returns:

a session with the user corresponding to the parameters specified, 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 servlet specified, 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 parameter specified, or null if no user can be authenticated.

getDeclaration

public abstract RepositoryDeclaration getDeclaration()

Returns general management information on this repository.

refreshSchemas

public abstract List refreshSchemas(boolean isFullRefresh)

Refreshes schemas and their associated contents loaded in the cache.

Parameters:

isFullRefresh - if true, all known schemas are invalidated, if false only schemas which have been updated since their last loading are invalidated.

Returns:

a list of SchemaLocation, the schemas that have been actually refreshed.

toStringInfo

public abstract String toStringInfo()

markHomeForPurge

public abstract void markHomeForPurge(AdaptationHome aHome,
                                      Session aSession)
                               throws OperationException

Marks the home specified for purge.

This operation is not reversible. However, this method does not perform physical purge. Physical purge will not be performed until calling method purgeHomes(Session). Marking a home for purge also marks all descendants of this home (that is, all child branches and versions, recursively) and their initial versions.

Parameters:

aHome - home to purge.

aSession - session that performs the operation, associated user must be administrator.

Throws:

OperationException - thrown if operation cannot complete (for example, a home is not closed).

See Also:

purgeHomes(Session), AdaptationHome.isMarkedForPurge()

purgeHomes

public abstract void purgeHomes(Session aSession)
                         throws OperationException

Purges the homes that have been marked for purge.

This operation is not reversible.

Homes can be marked for purge either by means of EBX.Manager or by calling method markHomeForPurge(AdaptationHome, Session).

Parameters:

aSession - session that performs the operation, associated user must be administrator.

Throws:

OperationException - thrown if operation cannot complete.