public abstract class Repository extends Object
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:
A dataspace or snapshot is represented by an instance of class AdaptationHome
.
"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.
"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.
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 getDefault()
to get the default repository instance.
Adaptation.getValidationReport()
). The main reasons are:
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:
Adaptation.isSchemaDefinitionCompliant(boolean)
(or Adaptation.getValidationReport()
);AdaptationHome
Modifier and Type | Field and Description |
---|---|
static BranchKey |
REFERENCE
Identifies the reference dataspace.
|
Modifier and Type | Method and 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.
|
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() |
public static final BranchKey REFERENCE
getReferenceBranch()
public static Repository getDefault()
If the thread is running within EBX®, it is strongly recommended to access the current repository from the provided context.
public abstract AdaptationHome getReferenceBranch()
The reference dataspace is always defined in the repository and it has no parent dataspace.
This method is equivalent to lookupHome(Repository.REFERENCE)
.
public abstract AdaptationHome lookupHome(HomeKey aKey)
null
if the specified dataspace or snapshot does not exist.lookupHome(boolean, HomeKey)
public abstract AdaptationHome lookupHome(boolean d3Lookup, HomeKey aKey)
If d3Lookup
is true
:
null
if the specified dataspace or snapshot does not exist.
If d3Lookup
is false
:
d3Lookup
parameter is ignored.
lookupHome(HomeKey)
.
public abstract void reopenHome(AdaptationHome aHome, Session aSession) throws OperationException
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).aHome
- home to reopen.aSession
- session that performs the reopening;
the associated user must be allowed to perform the operation.IllegalArgumentException
- if aHome
is null
.OperationException
- thrown if operation cannot complete.public abstract AdaptationHome createHome(HomeCreationSpec aSpec, Session aSession) throws OperationException
Note: This method cannot be called inside a procedure execution (because of transaction management restrictions).
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.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.).public abstract AdaptationHome createHome(AdaptationHome parentDataSpace, HomeKey aKey, Profile owner, Session aSession, UserMessage aLabel, UserMessage aDescription) throws OperationException
Note:
createHome(HomeCreationSpec, Session)
.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.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.).createHome(HomeCreationSpec, Session)
public abstract void setDocumentationLabel(AdaptationHome aDataSpaceOrSnapshot, String aLabel, Locale aLocale, Session aSession) throws OperationException
Note: This method cannot be called inside a procedure execution (because of transaction management restrictions).
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.IllegalArgumentException
- if aDataSpaceOrSnapshot
or locale
are
null
.OperationException
- thrown if operation cannot complete.public abstract void setDocumentationDescription(AdaptationHome aDataSpaceOrSnapshot, String aDescription, Locale aLocale, Session aSession) throws OperationException
Note: This method cannot be called inside a procedure execution (because of transaction management restrictions).
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.IllegalArgumentException
- if aDataSpaceOrSnapshot
or locale
are
null
.OperationException
- thrown if operation cannot complete.public abstract void closeHome(AdaptationHome aDataSpaceOrSnapshot, Session aSession) throws OperationException
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).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.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.public abstract Session createSessionFromLoginPassword(String login, String password) throws AuthenticationException
This method calls method
Directory.authenticateUserFromLoginPassword(String, String)
.
null
if login does not exist or password is incorrect.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).public abstract Session createSessionFromHttpRequest(HttpServletRequest httpServletRequest) throws AuthenticationException
This method calls method
Directory.authenticateUserFromHttpRequest(HttpServletRequest httpServletRequest)
.
null
if authentication features are not provided in the request.AuthenticationException
- if authentication cannot complete.public abstract Session createSessionFromSOAPHeader(Element header) throws AuthenticationException
This method calls method
Directory.authenticateUserFromSOAPHeader(Element)
.
null
if authentication features are not provided in the request.AuthenticationException
- if authentication cannot complete.public abstract Session createSessionFromArray(Object[] args)
This method calls method
Directory.authenticateUserFromArray(Object[])
.
null
if no user can be authenticated.public abstract SessionPermissions createSessionPermissionsForUser(UserReference aUserReference)
public abstract RepositoryDeclaration getDeclaration()
public abstract RepositoryPurge getPurgeDelegate()
public abstract DatabaseMapping getDatabaseMapping()
public abstract RepositoryAnonymizer newAnonymizer()
public abstract Locale getDefaultLocale()
public abstract List<Locale> getLocales()
public abstract void markHomeForPurge(AdaptationHome aDataSpaceOrSnapshot, Session aSession) throws OperationException
deleteHome(AdaptationHome, Session)
.OperationException
public abstract void deleteHome(AdaptationHome aDataSpaceOrSnapshot, Session aSession) throws OperationException
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.
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
.OperationException
- thrown if operation cannot complete (for example, if a dataspace or snapshot is not
closed).RepositoryPurge.purgeAll(Session)
,
getPurgeDelegate()
public abstract void purgeHomes(Session aSession) throws OperationException
purgeAll
.OperationException
public abstract RepositoryStatus getStatus()
public abstract List<SchemaLocation> refreshSchemas(boolean isFullRefresh)
isFullRefresh
- if true
, all known data models are invalidated, if false
only data models which have been updated since their last loading are invalidated.SchemaLocation
, the data models that
have actually been refreshed.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.public abstract String toStringInfo()