Package com.orchestranetworks.service

# Class ProgrammaticService

java.lang.Object
com.orchestranetworks.service.ProgrammaticService

public class ProgrammaticService extends Object
This class provides the ability to programmatically log a user session. This allows executing procedures in a well-defined context, for example in a scheduled task or in a batch.

To run a procedure from a user service, it is recommended to use `ServiceContext.execute(Procedure)` instead of this class, unless input parameters have to be specified (e.g. to have a specific behavior in triggers).

Warning: When modifying permissions in this context (by importing an EBX® archive or merging a dataspace programmatically), the session cache must be cleared via a call to Session.clearCache(). Otherwise, these modifications will not be reflected in the following operations.

### Using this class

In order to create an instance of this class, the external program must provide an authenticated session and a dataspace or snapshot:

>      ProgrammaticService.createForSession(Session, AdaptationHome)

In order to update the repository for import or export of data, a `Procedure.execute()` method must be called in a transactional container via:

>      ProgrammaticService.execute(Procedure)

### Code sample

     public class MyBatch implements Batch {

     public void executeBatch(Repository aRepository) throws Exception {
                    Session session = aRepository.createSessionFromLoginPassword("xxx", "yyy");
                    AdaptationHome dataSpace = aRepository.lookupHome(BranchKey.forName("myBranch"));
                    ProgrammaticService svc = ProgrammaticService.createForSession(session, dataSpace);
                    // optional
                    svc.setSessionTrackingInfo("My Script Sample");
                    Procedure proc = new Procedure()
                    {
                            public void execute(ProcedureContext aContext) throws Exception
                            {
                                    // ...
                            }
                    };
                    ProcedureResult result = svc.execute(proc);
                    if (result.hasErrors())
                    // ...
                    else
                    //...
                    }
     }
     }

See Also:
  - `ScheduledTask`
  - `Batch`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static ProgrammaticService`
  `createForSession(Session aSession, AdaptationHome aDataSpace)`
  Instantiates a service that will execute within the specified session in the specified dataspace.
  `static ProgrammaticService`
  `createForSession(Session aSession, AdaptationHome aDataSpace, Map<String,String> someInputParameters)`
  Instantiates a service that will be executed in the specified dataspace, and within a session cloned from `aSession` with specific input parameters.
  `ProcedureResult`
  `execute(Procedure aProcedure)`
  Executes the specified procedure.
  `AdaptationHome`
  `getCurrentHome()`
  Returns the current dataspace or snapshot of this service.
  `Session`
  `getSession()`
  Returns the current session of this service.
  `void`
  `setSessionTrackingInfo(String aTrackingInfo)`
  Specifies the session's tracking info.

  ### Methods inherited from class java.lang.Object

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

- ## Method Details

  - ### createForSession

    public static ProgrammaticService createForSession(Session aSession, AdaptationHome aDataSpace)
    Instantiates a service that will execute within the specified session in the specified dataspace.

  - ### createForSession

    public static ProgrammaticService createForSession(Session aSession, AdaptationHome aDataSpace, Map<String,String> someInputParameters)
    Instantiates a service that will be executed in the specified dataspace, and within a session cloned from `aSession` with specific input parameters.

    This is the same as `ProgrammaticService.createForSession(aSession.clone(someInputParameters), aDataSpace)`.

    See Also:
      - `Session.clone(Map)`
      - `Session.getInputParameterValue(boolean, String)`

  - ### execute

    public ProcedureResult execute(Procedure aProcedure)
    Executes the specified procedure. It calls in a transactional container the implementation of `Procedure.execute(ProcedureContext)`.
    Returns:
      the result of the execution (particularly, whether it has thrown an exception).

  - ### getCurrentHome

    public AdaptationHome getCurrentHome()
    Returns the current dataspace or snapshot of this service.

  - ### getSession

    public Session getSession()
    Returns the current session of this service.

  - ### setSessionTrackingInfo

    public void setSessionTrackingInfo(String aTrackingInfo)
    Specifies the session's tracking info.

    Note: This method has a side-effect: if the underlying session is obtained through a user interface container (for instance `UISessionContext.getSession()`), this method can impact all future events of this session. In such cases, it is recommended to reset the tracking info to its previous value once the work has been done.

    See Also:
      - `Session.getTrackingInfo()`