Package com.orchestranetworks.service

# Class Profile

java.lang.Object
com.orchestranetworks.service.Profile

Direct Known Subclasses:
  `Role`, `UserReference`

public abstract class Profile extends Object
Identifies a user profile for permission management. There are three types of profiles:

- A built-in role gives generic permissions in EBX®.
- A specific role is defined by a specific instance of `Directory`. For example, product manager, accountant.
- A user reference identifies a specific user by its login.

The relationship between each user and the roles he has is defined by the method `DirectoryHandler.isProfileIncluded(Profile, Profile)`.

See Also:
  - `Session`

- ## Field Summary

  Fields
  Modifier and Type
  Field
  Description
  `static final Role`
  `ADMINISTRATOR`
  Built-in 'Administrator' role.
  `static final Role`
  `EVERYONE`
  Built-in role, all users have this role.
  `static final Role`
  `OWNER`
  The dynamic built-in 'Owner' role.
  `static final Role`
  `READ_ONLY`
  Built-in read-only role.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `boolean`
  `equals(Object anObject)`
  `static Role`
  `forBuiltInRole(String roleName)`
  Returns the built-in role identified by the name specified.
  `String`
  `format()`
  Serializes a profile reference to a `String`.
  `static Role`
  `forSpecificRole(String roleName)`
  Returns the specific role identified by the name specified.
  `static UserReference`
  `forUser(String aUserId)`
  Returns the specified user reference.
  `static UserReference`
  `forUserWithSpecificPrivilege(String userId, ServiceKey servicePrivilegeGranted)`
  Returns the user reference specified, with the specific privilege granted.
  `static UserReference`
  `forUserWithSpecificPrivileges(String userId, Set<ServiceKey> servicePrivileges)`
  Returns the user reference specified, with the specific privileges granted.
  `String`
  `getLabel()`
  Returns the label of this profile.
  `int`
  `hashCode()`
  `boolean`
  `isBuiltIn()`
  Returns `true` if this profile is a built-in role.
  `boolean`
  `isBuiltInAdministrator()`
  Returns `true` if this `Profile` is the built-in "Administrator" role.
  `boolean`
  `isBuiltInEveryone()`
  Returns `true` if this Profile is the built-in "Everyone" role.
  `boolean`
  `isBuiltInOwner()`
  Returns `true` if this Profile is the built-in "Owner" role.
  `boolean`
  `isBuiltInReadOnly()`
  Returns `true` if this Profile is the built-in read-only role.
  `boolean`
  `isSpecificRole()`
  Returns `true` if this profile is a specific role.
  `boolean`
  `isUserReference()`
  Returns `true` if this profile references a user.
  `static Profile`
  `parse(String aString)`
  Analyzes a string that has been created using `format()` and returns the corresponding profile.
  `String`
  `toString()`

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

  `getClass, notify, notifyAll, wait, wait, wait`

- ## Field Details

  - ### ADMINISTRATOR

    public static final Role ADMINISTRATOR
    Built-in 'Administrator' role. The administrator role allows performing general administration tasks.

  - ### READ_ONLY

    public static final Role READ_ONLY
    Built-in read-only role.

    A user with the role read-only generally has no rights to perform any modifications in the EBX® repository (unless a procedure has explicitly deactivated access right controls, see `ProcedureContext.setAllPrivileges(boolean)`).

  - ### OWNER

    public static final Role OWNER
    The dynamic built-in 'Owner' role. A user is in the 'Owner' role when in a given dataset `A` and is in the "owner" profile defined by the root dataset of `A`.
    See Also:
      - `Session.isUserOwner(com.onwbp.adaptation.Adaptation)`

  - ### EVERYONE

    public static final Role EVERYONE
    Built-in role, all users have this role.

- ## Method Details

  - ### forBuiltInRole

    public static Role forBuiltInRole(String roleName) throws IllegalArgumentException
    Returns the built-in role identified by the name specified.

    Note: the recommended method of accessing a built-in role is through the available constants defined by this class: `EVERYONE`, `ADMINISTRATOR`, `READ_ONLY`, etc.

    Parameters:
      `roleName` - unique and persistent identifier of the specific role in the directory
    Throws:
      `IllegalArgumentException` - if the name specified does not correspond to a built-in role
    See Also:
      - `parse(String)`

  - ### forSpecificRole

    public static Role forSpecificRole(String roleName) throws IllegalArgumentException
    Returns the specific role identified by the name specified.

    Note: Calling this method does not imply that it returns a role that is actually defined in the current directory. The actual existence of a role is actually checked by the method `DirectoryHandler.isSpecificRoleDefined(Role)` (or `DirectoryHandler.isProfileDefined(Profile)`).

    Parameters:
      `roleName` - unique and persistent identifier of the specific role in the directory, corresponds to `Role.getRoleName()`.
    Throws:
      `IllegalArgumentException`
    See Also:
      - `parse(String)`

  - ### forUser

    public static UserReference forUser(String aUserId)
    Returns the specified user reference.

    Note: Calling this method does not imply that it returns a user that is actually defined in the current directory. The actual existence of a user is actually checked by the method `DirectoryHandler.isUserDefined(UserReference)`.

    Parameters:
      `aUserId` - a unique identifier of a user (usually its login), corresponds to `UserReference.getUserId()`.
    See Also:
      - `parse(String)`

  - ### forUserWithSpecificPrivilege

    public static UserReference forUserWithSpecificPrivilege(String userId, ServiceKey servicePrivilegeGranted)
    Returns the user reference specified, with the specific privilege granted.

    A privilege is useful when a user usually does not have the permissions to perform an operation, except in the context of a particular session. Concretely, such a session must have been granted the specific privilege in the method `Directory.authenticateUserFromHttpRequest(jakarta.servlet.http.HttpServletRequest)` or `Directory.authenticateUserFromArray(Object[])`.

    The following services can be specified for granting actual privileges:

    - `ServiceKey.CREATE`: the privilege to create a dataspace or snapshot (not to create a table record);
    - `ServiceKey.CLOSE`: the privilege to close a dataspace or snapshot;
    - `ServiceKey.MERGE`: the privilege to merge a dataspace.
    Parameters:
      `userId` - a unique identifier of a user (usually its login)
      `servicePrivilegeGranted` - grants the user the privilege of executing the service specified

  - ### forUserWithSpecificPrivileges

    public static UserReference forUserWithSpecificPrivileges(String userId, Set<ServiceKey> servicePrivileges)
    Returns the user reference specified, with the specific privileges granted.

    See the method `forUserWithSpecificPrivilege(String, ServiceKey)` for the list of the supported privileges.

    Parameters:
      `userId` - the unique identifier of a user (usually its login)
      `servicePrivileges` - set of `ServiceKey`s, grants the user the privilege of executing the services specified

  - ### parse

    public static Profile parse(String aString) throws IllegalArgumentException
    Analyzes a string that has been created using `format()` and returns the corresponding profile.

    Note: To explicitly get either a specific role or a user reference, the following methods must be called instead of this one: `forSpecificRole(String)`, `forUser(String)`.

    Throws:
      `IllegalArgumentException` - If `aString` is invalid.
    See Also:
      - `format()`

  - ### equals

    public boolean equals(Object anObject)
    Overrides:
      `equals` in class `Object`

  - ### hashCode

    public int hashCode()
    Overrides:
      `hashCode` in class `Object`

  - ### isBuiltIn

    public boolean isBuiltIn()
    Returns `true` if this profile is a built-in role.
    See Also:
      - `Role`

  - ### isBuiltInAdministrator

    public boolean isBuiltInAdministrator()
    Returns `true` if this `Profile` is the built-in "Administrator" role.

    See Also:
      - `ADMINISTRATOR`

  - ### isBuiltInReadOnly

    public boolean isBuiltInReadOnly()
    Returns `true` if this Profile is the built-in read-only role.

    See Also:
      - `READ_ONLY`

  - ### isBuiltInEveryone

    public boolean isBuiltInEveryone()
    Returns `true` if this Profile is the built-in "Everyone" role.

    See Also:
      - `EVERYONE`

  - ### isBuiltInOwner

    public boolean isBuiltInOwner()
    Returns `true` if this Profile is the built-in "Owner" role.

    See Also:
      - `OWNER`

  - ### isSpecificRole

    public boolean isSpecificRole()
    Returns `true` if this profile is a specific role.
    See Also:
      - `Role`

  - ### getLabel

    public String getLabel()
    Returns the label of this profile.
    - For a built-in role or a specific role, returns the role name.
    - For a user reference, returns the user identifier.
    The returned string should not be considered to be an identifier (for an identifier, use the method `format()`).

  - ### isUserReference

    public boolean isUserReference()
    Returns `true` if this profile references a user.
    See Also:
      - `UserReference`

  - ### toString

    public String toString()
    Overrides:
      `toString` in class `Object`

  - ### format

    public String format()
    Serializes a profile reference to a `String`.

    The string returned by this method can be persisted and should be used as an argument of the method `parse(String)` in order to recreate profile references.

    See Also:
      - `parse(String)`