Package com.orchestranetworks.service

Interface ProcedureContext

public interface ProcedureContext

Context to execute EBX® transactions.

See Also:

• Procedure.execute(ProcedureContext)

Method Summary

Modifier and Type	Method	Description
void	disableDatasetValidation(Adaptation aDataset)	Deprecated. Since 6.0.0, incremental validation is no longer triggered by a procedure.
Adaptation	doCopy(Adaptation aDataSet)	Copies the specified dataset.
Adaptation	doCopy(AdaptationReference aName, Adaptation aDataSet)	Copies the specified dataset and gives it the specified reference.
Adaptation	doCreateChild(AdaptationName aParentName, AdaptationReference requestedNameOrNull)	Creates a new dataset that is the child of the parent specified by aParentName.
Adaptation	doCreateChild(AdaptationName aParentName, AdaptationReference requestedNameOrNull, Profile owner)	Creates a new dataset that is the child of the parent specified by aParentName.
Adaptation	doCreateOcculting(ValueContext aKey, AdaptationTable aTable)	Creates an occulting record in the specified table.
Adaptation	doCreateOccurrence(ValueContext aContent, AdaptationTable aTable)	Creates a record in the specified table.
Adaptation	doCreateOccurrence(ValueContext aContent, AdaptationTable aTable, UserReference aCreator, Date aCreationTime, UserReference aLastUpdater, Date aLastUpdateTime)	Creates a record in the specified table with the specified system metadata.
Adaptation	doCreateOverwriting(ValueContext aContent, AdaptationTable aTable)	Deprecated.
Adaptation	doCreateRoot(ValueContext aContent, AdaptationTable aTable)	Deprecated.
Adaptation	doCreateRoot(SchemaLocation aSchemaLocation, AdaptationReference requestedNameOrNull, Profile owner)	Creates a new root dataset.
void	doDelete(AdaptationName aName, boolean isDeletingChildren)	Deletes the specified dataset or record.
void	doExport(ExportSpec aSpec)	Performs an export to an XML or CSV document.
void	doExportArchive(Archive anArchive)	Exports the current dataspace or snapshot to the specified EBX® archive.
void	doExportArchive(ArchiveExportSpec exportSpec)	Performs an export to an EBX® archive.
ImportResult	doImport(ImportSpec aSpec)	Imports XML or CSV content.
void	doImportArchive(Archive anArchive)	Imports the EBX® archive into the current dataspace.
void	doImportArchive(ArchiveImportSpec importSpec)	Imports the EBX® archive into the current dataspace with specifications.
void	doMergeToParent(AdaptationHome aSource)	Merges the specified dataspace to the current dataspace.
void	doMergeToParent(MergeSpecForHome aMergeSpec)	Performs the specified merge into the current dataspace.
Adaptation	doModifyContent(Adaptation aTarget, ValueContext aContent)	Modifies the content as specified.
Adaptation	doOccult(Adaptation aRecord)	Occults the specified record.
AdaptationHome	getAdaptationHome()	Returns the current dataspace.
int	getCommitThreshold()
ValueContextForUpdate	getContext(boolean isTriggerActivation, ValueContextForUpdate contextToCopy, AdaptationTable aTable)	Provides an interface for setting values on a context that conforms to any record of the specified table.
ValueContextForUpdate	getContext(AdaptationName aName)	Provides an interface for reading and/or updating persisted content.
ValueContextForUpdate	getContextForNewOccurrence(Adaptation recordToCopy, AdaptationTable aTable)	Provides an interface for copying a context from an existing record.
ValueContextForUpdate	getContextForNewOccurrence(AdaptationTable aTable)	Provides an interface for setting values on a context that conforms to any record of the specified table.
String	getExecutionInformation()
Date	getExecutionTimestamp()	Returns the timestamp of the current procedure execution.
String	getExecutionUUIDString()	Returns a universally unique identifier (UUID) for the current procedure execution.
Session	getSession()	Returns the current session context.
boolean	isAllPrivileges()	Default value is false.
boolean	isBlockingConstraintsDisabled()	Returns true if blocking constraints are disabled; by default, blocking constraints are enabled.
boolean	isDatabaseHistoryActivation()
boolean	isHistoryActivation()
boolean	isPrivilegeToModifyReferenceBranch()	Deprecated. Since version 5.0.0, the 'Reference' dataspace no longer has restricted behavior concerning direct modifications.
boolean	isReadOnly()	Returns true if called within a ReadOnlyProcedure.
boolean	isTriggerActivation()
void	setAllPrivileges(boolean allPrivileges)	If true, disables all permission checks for future operations performed by the current run.
default void	setBatch()	Deprecated. since 6.0.
void	setBlockingConstraintsDisabled(boolean isDisabled)	Disables or enables blocking constraints defined in the data model.
void	setCommitThreshold(int commitThreshold)	Sets the maximum size of the transaction so that intermediate commits occur during the execution of the procedure.
void	setDatabaseHistoryActivation(boolean isActivated)	Enables database history.
void	setExecutionInformation(String aString)	Specifies some additional information about the current execution.
void	setHistoryActivation(boolean isActivated)	Specifies whether the detailed XML audit trail is activated.
void	setInstanceActivation(Adaptation aDataSet, boolean activationState)	Activates or deactivates the specified dataset.
void	setInstanceDescription(Adaptation aDataSet, UserMessage aDescription)	Specifies a description for the specified dataset.
void	setInstanceLabel(Adaptation aDataSet, UserMessage aLabel)	Specifies a label for the specified dataset.
void	setInstanceOwner(Adaptation aDataSet, Profile newOwner)	Defines the owner of the specified dataset.
void	setPrivilegeToModifyReferenceBranch(boolean enable)	Deprecated. Since version 5.0.0, the 'Reference' dataspace no longer has restricted behavior concerning direct modifications.
void	setTriggerActivation(boolean isActivated)	Enables or disables triggers.

Method Details

doCreateRoot

Adaptation doCreateRoot(SchemaLocation aSchemaLocation,
 AdaptationReference requestedNameOrNull,
 Profile owner)
                 throws OperationException

Creates a new root dataset.

Parameters:

aSchemaLocation - Specifies the data model of the dataset to create. It must refer to a valid existing XML data model.

requestedNameOrNull - Specifies the public and persistent reference of the dataset to create. If null, the reference is allocated randomly.

owner - Specifies the profile that will own the newly created dataset (required).

Returns:

the newly created dataset.

Throws:

IllegalArgumentException - if the identifier does not conform to AdaptationReference.MAX_LENGTH and AdaptationReference.REFERENCE_PATTERN.

OperationException

See Also:

• doCreateChild(AdaptationName, AdaptationReference)
• doCreateChild(AdaptationName, AdaptationReference, Profile)

doCreateChild

Adaptation doCreateChild(AdaptationName aParentName,
 AdaptationReference requestedNameOrNull)
                  throws OperationException

Creates a new dataset that is the child of the parent specified by aParentName.

Parameters:

aParentName - Specifies the parent of the dataset to create. It must refer to an existing dataset in the current dataspace.

requestedNameOrNull - Specifies the public and persistent reference of the dataset to create. If null, this reference is allocated randomly.

Returns:

the newly created adaptation

Throws:

IllegalArgumentException - if identifier does not conform to AdaptationReference.MAX_LENGTH and AdaptationReference.REFERENCE_PATTERN.

OperationException

See Also:

• doCreateRoot(SchemaLocation, AdaptationReference, Profile)
• doCreateChild(AdaptationName, AdaptationReference, Profile)

doCreateChild

Adaptation doCreateChild(AdaptationName aParentName,
 AdaptationReference requestedNameOrNull,
 Profile owner)
                  throws OperationException

Creates a new dataset that is the child of the parent specified by aParentName.

Parameters:

aParentName - Specifies the parent of the dataset to create. It must refer to an existing dataset in the current dataspace.

requestedNameOrNull - Specifies the public and persistent reference of the dataset to create. If null, this reference is allocated randomly.

owner - Specifies the profile that will own the newly created dataset. If null, the owner of this dataset will be the profile that owns its parent.

Returns:

the newly created dataset.

Throws:

IllegalArgumentException - if identifier does not conform to AdaptationReference.MAX_LENGTH and AdaptationReference.REFERENCE_PATTERN.

OperationException

See Also:

• doCreateChild(AdaptationName, AdaptationReference)
• doCreateRoot(SchemaLocation, AdaptationReference, Profile)

doCopy

Adaptation doCopy(Adaptation aDataSet)
           throws OperationException

Copies the specified dataset. The new dataset will have the same parent and its reference will be allocated randomly.

This method is equivalent to:

Adaptation.doCopy(null, aDataSet);

Returns:

the copied adaptation.

Throws:

OperationException - if a record is specified instead of a dataset.

See Also:

• doCopy(AdaptationReference, Adaptation)

doCopy

Adaptation doCopy(AdaptationReference aName,
 Adaptation aDataSet)
           throws OperationException

Copies the specified dataset and gives it the specified reference. The new dataset will have the same parent as the one copied.

Validation

This method disables all blocking constraints defined in the data model during the copy operation. Only structural constraints remain blocking if records are copied into mapped tables.

Parameters:

aName - reference of the newly created dataset; if null, the reference is allocated randomly.

Returns:

the copied dataset.

Throws:

OperationException - if a record is specified instead of a dataset.

See Also:

• setBlockingConstraintsDisabled(boolean)

setInstanceLabel

void setInstanceLabel(Adaptation aDataSet,
 UserMessage aLabel)
               throws OperationException

Specifies a label for the specified dataset.

Throws:

OperationException

See Also:

• setInstanceDescription(Adaptation, UserMessage)

setInstanceDescription

void setInstanceDescription(Adaptation aDataSet,
 UserMessage aDescription)
                     throws OperationException

Specifies a description for the specified dataset.

Throws:

OperationException

See Also:

• setInstanceLabel(Adaptation, UserMessage)

setInstanceOwner

void setInstanceOwner(Adaptation aDataSet,
 Profile newOwner)
               throws OperationException

Defines the owner of the specified dataset.

Parameters:

newOwner - New owner can be either a user or a role.

Throws:

OperationException

Since:

5.7.0 this method now also applies to child datasets.

setInstanceActivation

void setInstanceActivation(Adaptation aDataSet,
 boolean activationState)
                    throws OperationException

Activates or deactivates the specified dataset.

Throws:

OperationException

doCreateOccurrence

Adaptation doCreateOccurrence(ValueContext aContent,
 AdaptationTable aTable)
                       throws OperationException,
ConstraintViolationException

Creates a record in the specified table. Depending on the specified content, this method performs the following operations:

1. If the specified content does not correspond to an existing record, a new record is created.
2. If the specified content corresponds to an existing record in inherit mode, it overwrites the existing record.
3. If the specified content corresponds to an existing record in occulting mode, it deletes the existing record before recreating the record.
4. If the specified content corresponds to an existing record in root or overwriting mode, an error is thrown.

Warning

Access rights on the table node for the current session are not checked when calling this method, even in a context which is not with "all privileges". SessionPermissions.getNodeAccessPermission(SchemaNode, Adaptation) should be used before executing this method to explicitly perform this check if required.

Parameters:

aContent - Specifies the content of the record to create. It must at least define its primary key. An object of this type is obtained by calling a getContext...(...) method, such as getContextForNewOccurrence(AdaptationTable).

aTable - Specifies the table where the record is to be created.

Returns:

the record that has been created.

Throws:

ConstraintViolationException - If the record to create contains values that do not comply with constraints in blocking mode.

OperationException

doCreateOccurrence

Adaptation doCreateOccurrence(ValueContext aContent,
 AdaptationTable aTable,
 UserReference aCreator,
 Date aCreationTime,
 UserReference aLastUpdater,
 Date aLastUpdateTime)
                       throws OperationException,
ConstraintViolationException

Creates a record in the specified table with the specified system metadata. This method should be used when migrating some data from another source and preserving the metadata (creator, creation time, last updater and last update time) is required.

Parameters:

aContent - Specifies the content of the record to create. It must at least define its primary key. An object of this type is obtained by calling a getContext...(...) method, such as getContextForNewOccurrence(AdaptationTable).

aTable - Specifies the table where the record is to be created.

aCreator - Specifies the creator of the record to be created

aCreationTime - Specifies the creation time of the record to be created

aLastUpdater - Specifies the last updater of the record to be created

aLastUpdateTime - Specifies the last update time of the record to be created

Returns:

the record that has been created.

Throws:

ConstraintViolationException - If the record to create contains values that do not comply with constraints in blocking mode.

NullPointerException - If any of the parameter is null.

OperationException

Since:

6.1.0

See Also:

• doCreateOccurrence(ValueContext, AdaptationTable)

doCreateRoot

@Deprecated
Adaptation doCreateRoot(ValueContext aContent,
 AdaptationTable aTable)
                 throws OperationException

Deprecated.

Creates a record in the specified table.

This method is deprecated since it has the same contract and effect as doCreateOccurrence(ValueContext, AdaptationTable).

Throws:

OperationException

doCreateOverwriting

@Deprecated
Adaptation doCreateOverwriting(ValueContext aContent,
 AdaptationTable aTable)
                        throws OperationException

Deprecated.

Creates a record in the specified table.

This method is deprecated since it has the same contract and effect as doCreateOccurrence(ValueContext, AdaptationTable).

Throws:

OperationException

doCreateOcculting

Adaptation doCreateOcculting(ValueContext aKey,
 AdaptationTable aTable)
                      throws OperationException

Creates an occulting record in the specified table.

Warning

Access rights on the table node for the current session are not checked when calling this method, even in a context which is not with "all privileges". SessionPermissions.getNodeAccessPermission(SchemaNode, Adaptation) should be used before executing this method to explicitly perform this check if required.

Parameters:

aKey - Specifies the key of the parent record to occult. An object of this type is obtained by calling the method getContext(AdaptationName) (the parent reference must be given as the argument), or getContextForNewOccurrence(AdaptationTable).

aTable - Specifies the table in which the occulting record is created.

Returns:

the record that defines the occulting.

Throws:

OperationException

See Also:

• getContextForNewOccurrence(AdaptationTable)

doOccult

Adaptation doOccult(Adaptation aRecord)
             throws OperationException

Occults the specified record.

Depending on the record specified, this method performs one of the following operations:

1. If the specified record is inheriting, it creates a new occulting record.
2. If the specified record is overwriting, it is replaced by a record in occulting mode.
3. If the specified record is occulting, it does nothing.
4. If the specified record is the root on a root dataset, an error is thrown.
5. If the specified record is the root on a non-root dataset, it is replaced by a record in occulting mode.

Warning

Access rights on the table node for the current session are not checked when calling this method, even in a context which is not with "all privileges". SessionPermissions.getNodeAccessPermission(SchemaNode, Adaptation) should be used before executing this method to explicitly perform this check if required.

Parameters:

aRecord - the record to be occulted.

Returns:

the occulted record.

Throws:

OperationException

doModifyContent

Adaptation doModifyContent(Adaptation aTarget,
 ValueContext aContent)
                    throws OperationException,
ConstraintViolationException

Modifies the content as specified. This method transparently applies modifications to datasets, as well as table records. For table records, two specific definition modes are handled, as follows:

1. If the specified content is an inherited record, a new overwriting record is created.
2. If the specified content is an occulting record, an error is thrown.

Caution: to access the modified record or dataset, it is necessary to use only the returned object, since the aTarget object passed as an argument will not be aware of the modification.

Parameters:

aTarget - The content to modify.

aContent - Specifies the modifications to apply. An object of this type is typically obtained by calling the method getContext(AdaptationName) (with the dataset or record to be modified passed as the parameter).

Returns:

the modified dataset or record.

Throws:

OperationException - if specified record is null or is in occulting mode.

ConstraintViolationException - if the specified record to modify contains values that do not comply with constraints in blocking mode.

See Also:

• getContext(AdaptationName)

doDelete

void doDelete(AdaptationName aName,
 boolean isDeletingChildren)
       throws OperationException,
ConstraintViolationException

Deletes the specified dataset or record.

If deleting a record that is an inherited record, this method will create an occulting record (see method doOccult(Adaptation)).

Warning

Access rights on the table node for the current session are not checked when calling this method, even in a context which is not with "all privileges". SessionPermissions.getNodeAccessPermission(SchemaNode, Adaptation) should be used before executing this method to explicitly perform this check if required.

Parameters:

aName - reference of the dataset or record to be deleted.

isDeletingChildren - if set to true, all children will be deleted recursively.

Throws:

ConstraintViolationException - if the specified record or dataset is being referenced by a foreign key constraint (osd:tableRef) in blocking mode.

OperationException

getAdaptationHome

AdaptationHome getAdaptationHome()

Returns the current dataspace.

doImport

ImportResult doImport(ImportSpec aSpec)
               throws OperationException

Imports XML or CSV content.

For XML content, this operation is tolerant of the implicit schema of the XML source. That is, if some elements do not exist in target's data model, they are simply ignored.

Warning

Access rights on the table node for the current session are not checked when calling this method, even in a context which is not with "all privileges". SessionPermissions.getNodeAccessPermission(SchemaNode, Adaptation) should be used before executing this method to explicitly perform this check if required.

Parameters:

aSpec - definition of the import.

Returns:

the result of the import.

Throws:

OperationException - if an error occurs during the operation (for example, if an integrity constraint is violated in the source content).

See Also:

• doExport(ExportSpec)

doExport

void doExport(ExportSpec aSpec)
       throws OperationException

Performs an export to an XML or CSV document.

Parameters:

aSpec - definition of the export.

Throws:

OperationException - if an error occurs during the operation.

See Also:

• doImport(ImportSpec)

doExportArchive

void doExportArchive(Archive anArchive)
              throws OperationException

Exports the current dataspace or snapshot to the specified EBX® archive.

Throws:

OperationException

See Also:

• doExportArchive(ArchiveExportSpec)

doExportArchive

void doExportArchive(ArchiveExportSpec exportSpec)
              throws OperationException

Performs an export to an EBX® archive.

It is possible to perform a data transformation upon export by specifying a NodeDataTransformer on the data model.

Throws:

OperationException

See Also:

• doImportArchive(ArchiveImportSpec)

doImportArchive

void doImportArchive(Archive anArchive)
              throws OperationException

Imports the EBX® archive into the current dataspace.

This method is equivalent to:

 ProcedureContext.doImportArchive(ArchiveImportSpecModeDEFAULT);
 

Throws:

OperationException

See Also:

• doImportArchive(ArchiveImportSpec)
• ArchiveImportSpecMode.DEFAULT

doImportArchive

void doImportArchive(ArchiveImportSpec importSpec)
              throws OperationException

Imports the EBX® archive into the current dataspace with specifications.

The import mode is specified using the method ArchiveImportSpec.setMode(ArchiveImportSpecMode).

Validation

This method disables all blocking constraints defined in the data model during the import archive operation. Only structural constraints remain blocking if records are being imported into mapped tables.

Permissions

This method disables all permission checks using setAllPrivileges(boolean). Therefore, before calling this method, it is important to guarantee that the current session is actually able to execute the import.

For more information, see ServicePermissionRule and Session.isUserInRole(Profile).

Throws:

OperationException

See Also:

• doExportArchive(ArchiveExportSpec)
• ArchiveImportSpecMode

doMergeToParent

void doMergeToParent(AdaptationHome aSource)
              throws OperationException

Merges the specified dataspace to the current dataspace.

This method is equivalent to doMergeToParent(MergeSpecForHome), with all datasets selected in the source dataspace associated with the MergeSpecForHome.

Throws:

OperationException

See Also:

• doMergeToParent(MergeSpecForHome)

doMergeToParent

void doMergeToParent(MergeSpecForHome aMergeSpec)
              throws OperationException

Performs the specified merge into the current dataspace.

For the selected content to be merged, every change between the initial snapshot of the source and its current state is applied to the current dataspace. The changes are applied even if they conflict with the changes performed on the current dataspace in the meantime.

Throws:

IllegalArgumentException - when MergeSpecForHome is null or when MergeSpecForHome.getHomeToMerge() is:

• the 'Reference' dataspace,
• a snapshot,
• null,
• not a child of the current dataspace.

OperationException - when the merge cannot be completed successfully.

See Also:

• doMergeToParent(AdaptationHome)

getCommitThreshold

int getCommitThreshold()

See Also:

• setCommitThreshold(int)

setCommitThreshold

void setCommitThreshold(int commitThreshold)

Sets the maximum size of the transaction so that intermediate commits occur during the execution of the procedure.

Attention: Doing intermediate commits breaks transaction atomicity. It can leave the database in an intermediate state and clients can see the committed intermediate states. This is particularly true for direct SQL access to tables in mapped modes (history and replica tables). Consequently, this method must be used only in particular cases where atomicity does not matter, for example, in the case of a repeatable data import in an environment without any SQL clients.

If commitThreshold > 0, a commit will occur every time the number of current changes is equal to commitThreshold. If commitThreshold = 0, only one commit occurs (after the procedure execution returns).

If unspecified, the commit threshold is '0'.

Records are gathered by blocks and a change refers to one modified block. This means that if several records are updated (created, modified, or deleted) in the same block, they will be counted as only one change. Since a block groups up to 256 records, the number of actual records creates, updates, and deletes (Ncud) in a single commit can obtained by the following formula:

commitThreshold <= Ncud <= 256 * commitThreshold

For example, for an initial import, if the commit threshold is set to '50', a commit will occur periodically, each for a maximum of 12800 record creations.

All database updates are executed just before the database commit.

If the table has history activated, an additional change must be counted for each record create, update, or delete. If the table has an onCommit replication activated, an additional change must be counted for each record create, update, or delete. If an onDemand replication refresh is requested, no change is counted; see ReplicationUnit.performRefresh(ProcedureContext).