Package com.orchestranetworks.service

# Interface Session

public interface Session
Represents an authenticated user session, either an HTTP session or a "programmatic" session.

In a user interface container, the current HTTP session is usually obtained by a method named `getSession`, for instance `UISessionContext.getSession()`. Outside of the user interface, a new programmatic session is obtained by calling the methods:

- `Repository.createSessionFromLoginPassword(String, String)`,
- `Repository.createSessionFromHttpRequest(HttpServletRequest)`.
- `Repository.createSessionFromArray(Object[])`.

Also, sessions can be instantiated through the data service authentication process.

See Also:
  - `Directory`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `void`
  `clearCache()`
  Clears the session's local caches on user's roles and permissions.
  `Session`
  `clone(Map<String,String> someInputParameters)`
  Returns a session cloned from this session with specific input parameters.
  `Object`
  `getAttribute(String aName)`
  Returns the object bound to the specified name in this session, or `null` if no object is bound to the specified name.
  `Set<String>`
  `getAttributeNames()`
  Returns a `Set` of `String` objects containing the names of all the objects bound to this session.
  `DirectoryHandler`
  `getDirectory()`
  Returns the directory used for authentication.
  `String`
  `getHttpSessionId()`
  If known, returns a string containing the unique identifier assigned to the current HTTP session.
  `String`
  `getInputParameterValue(boolean lookupInParentSessions, String aParameterName)`
  Returns the value of the specified input parameter, `null` if this parameter cannot be found.
  `SessionInteraction`
  `getInteraction(boolean lookupInParentSessions)`
  Returns the workflow interaction associated with this session.
  `String`
  `getIpAddress()`
  If known, returns the Internet Protocol (IP) address of the client that sent the request.
  `Locale`
  `getLocale()`
  Returns the session's current locale.
  `default Locale`
  `getLocaleForSchemaNode(SchemaNode aDataModelNode)`
  Deprecated.
  Since 5.9.0 this method is useless because it is not possible to define locales for a module anymore.
  `SessionPermissions`
  `getPermissions()`
  Returns the current user's permission facade.
  `String`
  `getTrackingInfo()`
  Returns this session's tracking information, if specified.
  `String`
  `getUserEmail()`
  Returns the user's email address.
  `UserReference`
  `getUserReference()`
  Returns the user's user reference in the directory.
  `boolean`
  `isInWorkflowInteraction(boolean lookupInParentSessions)`
  Returns `true` when the current session is in the context of a workflow interaction.
  `boolean`
  `isSystemUser()`
  Returns `true` for a System session.
  `boolean`
  `isUserInRole(Profile aProfile)`
  Returns `true` if the current user or the session has the specified profile.
  `boolean`
  `isUserInRoles(Iterable<Profile> profiles)`
  Returns `true` if the current user or the session has at least one profile from the specified profile list.
  `boolean`
  `isUserOwner(Adaptation aDataset)`
  Returns `true` if this user is an owner of the specified dataset.
  `boolean`
  `isUserOwner(AdaptationHome aDataspace)`
  Returns `true` if this user is an owner of the specified dataspace.
  `void`
  `setAttribute(String aName, Object aValue)`
  Binds an object to this session, using the name specified.

- ## Method Details

  - ### getIpAddress

    String getIpAddress()
    If known, returns the Internet Protocol (IP) address of the client that sent the request. This is the same as the value of the CGI variable `REMOTE_ADDR`.

  - ### getHttpSessionId

    String getHttpSessionId()
    If known, returns a string containing the unique identifier assigned to the current HTTP session. The identifier is assigned by the servlet container and depends on its implementation.

  - ### getLocale

    Locale getLocale()
    Returns the session's current locale.

    This locale is determined in the following order:

    1. the locale attached to the user session (if the session was created in this context)
    2. the default product locale (see Configuring EBX® localization).

  - ### getLocaleForSchemaNode

    @Deprecated default Locale getLocaleForSchemaNode(SchemaNode aDataModelNode)
    Deprecated.
    Since 5.9.0 this method is useless because it is not possible to define locales for a module anymore. Now it returns the result of `getLocale()`, which should be used instead.

  - ### getTrackingInfo

    String getTrackingInfo()
    Returns this session's tracking information, if specified. Tracking information is logged in the `frontEnd` category and in the EBX® history for all transactions run by this session that trigger some history.

    Tracking information is specified on the session creation and is immutable. The way it is specified depends on the context:

    - for a Web component, via the method `UIHttpManagerComponent.setTrackingInfo(String)`;
    - in a programmatic service, using the method `ProgrammaticService.setSessionTrackingInfo(String)`;
    - in a SOAP request of a data service.
    - in a REST request of a data service.
    See Also:
      - `getInputParameterValue(boolean, String)`
      - `ProcedureContext.setExecutionInformation(String)`

  - ### getUserReference

    UserReference getUserReference()
    Returns the user's user reference in the directory.

    Never returns `null`. In case of a System session, returns the 'ebx-systemUser' constant.

    See Also:
      - `isSystemUser()`

  - ### getUserEmail

    String getUserEmail()
    Returns the user's email address.

  - ### getDirectory

    DirectoryHandler getDirectory()
    Returns the directory used for authentication.
    Since:
      5.2.0

  - ### getInteraction

    SessionInteraction getInteraction(boolean lookupInParentSessions)
    Returns the workflow interaction associated with this session.

    An interaction is initiated and closed through a work item and allows to share parameters between the user interface and a workflow user task.

    Parameters:
      `lookupInParentSessions` - if `true`, looks up an interaction in this session or, if none is found, looks in its parent session recursively; if `false`, the lookup is only performed on this session.
    Since:
      5.2.7
    See Also:
      - `com.orchestranetworks.workflow`
      - Parameters declaration and availability in workflows and perspectives

  - ### isInWorkflowInteraction

    boolean isInWorkflowInteraction(boolean lookupInParentSessions)
    Returns `true` when the current session is in the context of a workflow interaction.

    Invoking this method is equivalent to:

         getInteraction(lookupInParentSessions) != null

    Parameters:
      `lookupInParentSessions` - if `true`, this method will also return `true` if a parent session is in the context of a workflow. If `false`, only the current session context is evaluated.
    Since:
      5.8.0

  - ### getInputParameterValue

    String getInputParameterValue(boolean lookupInParentSessions, String aParameterName)
    Returns the value of the specified input parameter, `null` if this parameter cannot be found. Input parameters are specified on the session creation, they are immutable. The way they are specified depends on the context:
    - For a Web component, input parameters are specified by the initial HTTP request that created this session. If the request has a multi-valued parameter, the value returned by this method is equal to the first parameter in the request.
    - In a workflow interaction, input parameters are specified according to the mapping specified by the user task definition in the workflow model.
    - In a SOAP data service, the input parameters are specified in the request.
    - In a REST data service, the input parameters are specified in the request.
    - In a programmatic service, input parameters are specified via `ProgrammaticService.createForSession(Session, AdaptationHome, Map)`.

    Notes:

    1. For a Web component and a workflow interaction, built-in parameters are ignored, they are not included as input parameters returned by this method. Built-in parameters are documented in the chapter Using EBX® as a Web Component.
    2. If this session is under a workflow interaction, it can be a child session of a parent created through a Web component call. In such a case, specific input parameters of the initial Web component will always be ignored.
    Parameters:
      `lookupInParentSessions` - if `true`, looks up the parameter in this session or, if none is found, looks in its parent session recursively ; if `false`, the lookup is only performed on this session.
      `aParameterName` - the name of the parameter to be looked up in the initial HTTP request that created this session.
    Since:
      5.6.0
    See Also:
      - Using EBX® as a Web Component
      - `getInteraction(boolean)`

  - ### getPermissions

    SessionPermissions getPermissions()
    Returns the current user's permission facade.

    This allows checking the user's permissions on dataspaces, datasets, and nodes (tables, ...).

  - ### isUserInRole

    boolean isUserInRole(Profile aProfile)
    Returns `true` if the current user or the session has the specified profile. If the specified profile is a role, this result means that the user belongs to the specified role. If the specified profile is a `UserReference`, this means that the current session user has this `reference`.

    For performance reasons, it is recommended to use `isUserInRoles(Iterable)` to evaluate a list of profiles.

    See Also:
      - `isUserInRoles(Iterable)`

  - ### isUserInRoles

    boolean isUserInRoles(Iterable<Profile> profiles)
    Returns `true` if the current user or the session has at least one profile from the specified profile list.

    The method evaluates each profile of the list as follows: if the profile is a role, the method checks if the user belongs to the specified role ; if the specified profile is a `UserReference`, the method checks that the current session user has this `reference`. As soon as profile of the list matches with a profile of the user, the method returns `true`.

    Since:
      5.7.1 fix K
    See Also:
      - `isUserInRole(Profile)`

  - ### clearCache

    void clearCache()
    Clears the session's local caches on user's roles and permissions.

  - ### isSystemUser

    boolean isSystemUser()
    Returns `true` for a System session.

    A System session has no permission restrictions. It is created only by EBX® internal code (it cannot be created through the standard `directory authentication processes`).

    A System session has no associated roles: internal permission resolutions bypass role-based permission rules and more generally any permission rule. The user id dedicated to the System session is 'ebx-systemUser'. It can appear in some places, for example as the `ebxd:lastUser` attribute available in CSV and XML contents.

    Since:
      5.2.7

  - ### isUserOwner

    boolean isUserOwner(Adaptation aDataset)
    Returns `true` if this user is an owner of the specified dataset.

    Unless otherwise specified in a permission rule, a user that owns a dataset has no access restrictions on it.

  - ### isUserOwner

    boolean isUserOwner(AdaptationHome aDataspace)
    Returns `true` if this user is an owner of the specified dataspace.

    Unless otherwise specified in a permission rule, a user that owns a dataspace has no access restrictions on it.

    Since:
      6.0

  - ### getAttribute

    Object getAttribute(String aName)
    Returns the object bound to the specified name in this session, or `null` if no object is bound to the specified name.
    Parameters:
      `aName` - a string specifying the name of the object
    Returns:
      the object with the specified name

  - ### getAttributeNames

    Set<String> getAttributeNames()
    Returns a `Set` of `String` objects containing the names of all the objects bound to this session.
    Returns:
      an unmodifiable `Set` of `String` objects specifying the names of all the objects bound to this session

  - ### setAttribute

    void setAttribute(String aName, Object aValue)
    Binds an object to this session, using the name specified. If an object of the same name is already bound to the session, the previous object is replaced.

    If the value passed in is `null`, this removes the object previously bound.

    Warning: setting an attribute will impact all existing sub-sessions as well as the parent session, recursively (if this session is not a root session).

    Parameters:
      `aName` - the name to which the object is bound
      `aValue` - the object to be bound
    Throws:
      `IllegalArgumentException` - if `aName` is `null`

  - ### clone

    Session clone(Map<String,String> someInputParameters)
    Returns a session cloned from this session with specific input parameters.

    In the resulting `Session`:

    - if any, original input parameters are replaced by the ones specified.
    - `getInteraction(boolean)` always returns `null` (because it contains input parameters in a workflow context).
    See Also:
      - `Session`