Package com.orchestranetworks.service

Interface ProcedureContext

public interface ProcedureContext
Container for EBX® transactions.
See Also:

  • 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

      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:

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

    • 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

      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:

    • setInstanceLabel

      void setInstanceLabel(Adaptation aDataSet, UserMessage aLabel) throws OperationException
      Specifies a label for the specified dataset.
      Throws:
      OperationException
      See Also:

    • setInstanceDescription

      void setInstanceDescription(Adaptation aDataSet, UserMessage aDescription) throws OperationException
      Specifies a description for the specified dataset.
      Throws:
      OperationException
      See Also:

    • 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

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

    • 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 aContentobject passed as an argument will, in some cases, 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:

    • 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

      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:

    • doExportArchive

      void doExportArchive(Archive anArchive) throws OperationException
      Exports the current dataspace or snapshot to the specified EBX® archive.
      Throws:
      OperationException
      See Also:

    • 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

      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

      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:

    • 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

      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:

    • getCommitThreshold

      int getCommitThreshold()
      See Also:

    • 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 (tables in relational mode, history tables 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'.

      Internally, the changes are counted differently, depending on whether the updated table is in relational mode or not:

      1. If the table is in relational mode, each record create, update, or delete is counted as one change.
      2. If the table is in semantic mode, 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 100 records, the number of actual records creates, updates, and deletes (Ncud) in a single commit can obtained by the following formula:

        commitThreshold <= Ncud <= 100 * 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 5000 record creations.

        When not in relational mode, all database updates are executed just before the database commit. The number of SQL queries per modified block is between 2 and a number dependent on record size.

      3. If the table has history activated, an additional change must be counted for each record create, update, or delete.
      4. If the table has an onCommit replication activated, an additional change must be counted for each record create, update, or delete.
      5. If an onDemand replication refresh is requested, no change is counted; see ReplicationUnit.performRefresh(ProcedureContext).
      Throws:
      IllegalArgumentException - if commitThreshold < 0.

    • isHistoryActivation

      boolean isHistoryActivation()
      See Also:

    • setHistoryActivation

      void setHistoryActivation(boolean isActivated)
      Specifies whether the detailed XML audit trail is activated.

      By default, detailed XML audit trail is activated.

    • isDatabaseHistoryActivation

      boolean isDatabaseHistoryActivation()
      See Also:

    • setDatabaseHistoryActivation

      void setDatabaseHistoryActivation(boolean isActivated)
      Enables database history. Default is true.

    • isTriggerActivation

      boolean isTriggerActivation()
      See Also:

    • setTriggerActivation

      void setTriggerActivation(boolean isActivated)
      Enables or disables triggers.

      If not specified, triggers are enabled.

      Disabling triggers means disabling all trigger methods defined by InstanceTrigger and by TableTrigger, except for TableTrigger.handleBeforeTransactionCommit(BeforeTransactionCommitContext), which is always executed.

    • isReadOnly

      boolean isReadOnly()
      Returns true if called within a ReadOnlyProcedure.

    • isBlockingConstraintsDisabled

      boolean isBlockingConstraintsDisabled()
      Returns true if blocking constraints are disabled; by default, blocking constraints are enabled.
      Since:
      5.4.2
      See Also:

    • setBlockingConstraintsDisabled

      void setBlockingConstraintsDisabled(boolean isDisabled)
      Disables or enables blocking constraints defined in the data model.

      If not disabled by this method, blocking constraints defined in the data model using the property 

       <osd:validation>
         <blockCommits>onInsertUpdateOrDelete</blockCommits>
 </osd:validation>
      will be checked before any operation is performed and throw a ConstraintViolationException if it does not comply with such a constraint.

      Disabling blocking constraints means disabling all constraints explicitly defined in data model as blocking commits.

      This method does not disable structural constraints that automatically become blocking constraints in relational tables, or when table history or replication is activated.

      Import and copy operations

      This method has no effect for archive imports and dataset copying. This is because all blocking constraints are always disabled when importing archives and copying datasets.

      Since:
      5.4.2
      See Also:

    • disableDatasetValidation

      void disableDatasetValidation(Adaptation aDataset)
      Disables the constraints defined in the data model of the specified dataset during the execution of this procedure. That is, incremental validation will be disabled on the specified dataset when executing this procedure.

      The use of this method may be useful when performing mass modifications during a procedure. Indeed, disabling the incremental validation avoids validating each update performed on the specified dataset and it can then lead to important performance improvements during mass updates.

      This method does not disable:

      • blocking constraints defined in the data model;
      • structural constraints that automatically become blocking constraints in relational tables, or when table history or replication is activated.

      A call to this method implies the reset of:

      • the validation report of the specified dataset and its children at the end of this procedure;
      • the validation states of the constraints in other datasets that depend on the specified dataset. That is, if a constraint in another dataset defines a dependency to a table in the specified dataset, then the validation state of this constraint will be reset at the end of this procedure.

      Throws:
      IllegalArgumentException - if the specified Adaptation is null or if it is not a dataset.
      Since:
      5.9.0
      See Also:

    • setBatch

      void setBatch()
      Defines a context for mass modifications. Actually, it only disables the explicit existence check issued for the record before creation. As a result, a technical error will be raised instead of a functional error when a duplicate record is created (yet, the primary key constraint is always enforced).

      Activating this mode is only relevant for relational tables. It can then lead to important performance improvements, especially when performing massive modifications. On the other hand, this mode will have little to no effect if, for a given table, a small number of distinct statements alternate in sequence (for example: one UPDATE, then one SELECT, then one DELETE, then one INSERT).

      This feature can be activated only once by procedure. Subsequent calls to this method are silently ignored. Once activated, the feature cannot be deactivated while the procedure is running.

      Since:
      5.7.0.

    • getExecutionInformation

      String getExecutionInformation()
      See Also:

    • setExecutionInformation

      void setExecutionInformation(String aString)
      Specifies some additional information about the current execution.

      If specified, the information is displayed in the history log. If unspecified, only the procedure class name is displayed.

      The execution information plays a similar role as session tracking info, but more locally, that is, in the context of a single execution.

      See Also:

    • isAllPrivileges

      boolean isAllPrivileges()
      Default value is false.
      See Also:

    • setAllPrivileges

      void setAllPrivileges(boolean allPrivileges)
      If true, disables all permission checks for future operations performed by the current run. If false, sets the default mode that enables the usual permission checks.

      Caution: When a procedure disables all permission checks, the client code must check that the current user session is actually allowed to run the procedure.

      See Also:

    • isPrivilegeToModifyReferenceBranch

      @Deprecated boolean isPrivilegeToModifyReferenceBranch()
      Deprecated.
      Since version 5.0.0, the 'Reference' dataspace no longer has restricted behavior concerning direct modifications. This method always returns true.

    • setPrivilegeToModifyReferenceBranch

      @Deprecated void setPrivilegeToModifyReferenceBranch(boolean enable)
      Deprecated.
      Since version 5.0.0, the 'Reference' dataspace no longer has restricted behavior concerning direct modifications. This method does nothing.

    • getContextForNewOccurrence

      ValueContextForUpdate getContextForNewOccurrence(AdaptationTable aTable)
      Provides an interface for setting values on a context that conforms to any record of the specified table. This context is useful for specifying a parent or a new root record.

      This method is equivalent to getContext(isTriggerActivation(), null, aTable).

      See Also:

    • getContextForNewOccurrence

      ValueContextForUpdate getContextForNewOccurrence(Adaptation recordToCopy, AdaptationTable aTable)
      Provides an interface for copying a context from an existing record. This context is useful for specifying a parent or a new root record.

      If a trigger has been specified, the method TableTrigger.handleNewContext(NewTransientOccurrenceContext) is invoked, unless triggers have been disabled.

      Duplicating a record with read-only or hidden fields

      See TableTrigger.handleNewContext(NewTransientOccurrenceContext) documentation note.

      See Also:

    • getContext

      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. This context is useful for specifying a parent or a new root record.
      Parameters:
      isTriggerActivation - if false, the method TableTrigger.handleNewContext(NewTransientOccurrenceContext) is not invoked. See also isTriggerActivation().
      contextToCopy - if not null, the content is copied to the context to be returned.
      aTable - the new context conforms to the data model of this table.
      See Also:

    • getContext

      ValueContextForUpdate getContext(AdaptationName aName)
      Provides an interface for reading and/or updating persisted content.
      See Also:

    • getExecutionTimestamp

      Date getExecutionTimestamp()
      Returns the timestamp of the current procedure execution.

    • getExecutionUUIDString

      String getExecutionUUIDString()
      Returns a universally unique identifier (UUID) for the current procedure execution. This identifier is logged in the history and can be used, for example, to identify it in exports.

      The UUID format used is the hexadecimal representation of UUID Leach-Salz variant, version 1 (time-based).

      For more information, see the Internet-Draft UUIDs and GUIDs or the standards body definition at ISO/IEC 11578:1996 .

    • getSession

      Session getSession()
      Returns the current session context.