# ClientPrincipalResource.java

    /*
    ** Module   : ClientPrincipalResource.java
    ** Abstract : Defines APIs for CLIENT-PRINCIPAL resource.
    **
    ** Copyright (c) 2018-2025, Golden Code Development Corporation.

    **
    ** -#- -I- --Date-- --------------------------------Description-----------------------------------
    ** 001 CA  20181128 Created initial version.
    ** 002 IAS 20190507 Added more attributes and methods.
    ** 003 IAS 20190524 Added support for CLIENT-PRINCIPAL:(LOGIN-STATE, LOGIN-EXPIRATION-TIMESTAMP,
    **                  SEAL-TIMESTAMP)
    ** 004 IAS 20190625 Added support for SECURITY-POLICY:SET-CLIENT
    ** 005 IAS 20190703 Changed support for SET-DB-CLIENT
    ** 006 GBB 20230719 Fix for SESSION-ID, moved to a separate interface.
    ** 007 ICP 20250312 Added support for TENANT-ID and TENANT-NAME functions.
    */
    /*
    ** This program is free software: you can redistribute it and/or modify
    ** it under the terms of the GNU Affero General Public License as
    ** published by the Free Software Foundation, either version 3 of the
    ** License, or (at your option) any later version.
    **
    ** This program is distributed in the hope that it will be useful,
    ** but WITHOUT ANY WARRANTY; without even the implied warranty of
    ** MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    ** GNU Affero General Public License for more details.
    **
    ** You may find a copy of the GNU Affero GPL version 3 at the following
    ** location: https://www.gnu.org/licenses/agpl-3.0.en.html
    **
    ** Additional terms under GNU Affero GPL version 3 section 7:
    **
    **   Under Section 7 of the GNU Affero GPL version 3, the following additional
    **   terms apply to the works covered under the License.  These additional terms
    **   are non-permissive additional terms allowed under Section 7 of the GNU
    **   Affero GPL version 3 and may not be removed by you.
    **
    **   0. Attribution Requirement.
    **
    **     You must preserve all legal notices or author attributions in the covered
    **     work or Appropriate Legal Notices displayed by works containing the covered
    **     work.  You may not remove from the covered work any author or developer
    **     credit already included within the covered work.
    **
    **   1. No License To Use Trademarks.
    **
    **     This license does not grant any license or rights to use the trademarks
    **     Golden Code, FWD, any Golden Code or FWD logo, or any other trademarks
    **     of Golden Code Development Corporation. You are not authorized to use the
    **     name Golden Code, FWD, or the names of any author or contributor, for
    **     publicity purposes without written authorization.
    **
    **   2. No Misrepresentation of Affiliation.
    **
    **     You may not represent yourself as Golden Code Development Corporation or FWD.
    **
    **     You may not represent yourself for publicity purposes as associated with
    **     Golden Code Development Corporation, FWD, or any author or contributor to
    **     the covered work, without written authorization.
    **
    **   3. No Misrepresentation of Source or Origin.
    **
    **     You may not represent the covered work as solely your work.  All modified
    **     versions of the covered work must be marked in a reasonable way to make it
    **     clear that the modified work is not originating from Golden Code Development
    **     Corporation or FWD.  All modified versions must contain the notices of
    **     attribution required in this license.
    */

    package com.goldencode.p2j.util;

    /**
     * Defines all attributes and methods required by the CLIENT-PRINCIPAL resource.
     */
    @LegacyResource(resource = LegacyResource.CLIENT_PRINCIPAL)
    public interface ClientPrincipalResource
    {
       /**
        * Get the USER-ID attribute.
        *
        * @return   See above.
        */
       @LegacyAttribute(name = "USER-ID")
       public character getUserId();

       /**
        * Set the USER-ID Attribute.
        *
        * @param    userId
        *           The value of the USER-ID attribute.
        */
       @LegacyAttribute(name = "USER-ID", setter = true)
       public void setUserId(character userId);

       /**
        * Set the USER-ID Attribute.
        *
        * @param    userId
        *           The value of the USER-ID attribute.
        */
       @LegacyAttribute(name = "USER-ID", setter = true)
       public void setUserId(String userId);

       /**
        * Get the DOMAIN-TYPE attribute.
        *
        * @return   See above.
        */
       @LegacyAttribute(name = "DOMAIN-TYPE")
       public character getDomainType();

       /**
        * Set the DOMAIN-TYPE Attribute.
        *
        * @param    domainType
        *           The value of the DOMAIN-TYPE attribute.
        */
       @LegacyAttribute(name = "DOMAIN-TYPE", setter = true)
       public void setDomainType(character domainType);

       /**
        * Set the DOMAIN-TYPE Attribute.
        *
        * @param    domainType
        *           The value of the DOMAIN-TYPE attribute.
        */
       @LegacyAttribute(name = "DOMAIN-TYPE", setter = true)
       public void setDomainType(String domainType);

       /**
        * Get the DOMAIN-NAME attribute.
        *
        * @return   See above.
        */
       @LegacyAttribute(name = "DOMAIN-NAME")
       public character getDomainName();

       /**
        * Set the DOMAIN-NAME Attribute.
        *
        * @param    domainName
        *           The value of the DOMAIN-NAME attribute.
        */
       @LegacyAttribute(name = "DOMAIN-NAME", setter = true)
       public void setDomainName(character domainName);

       /**
        * Set the DOMAIN-NAME Attribute.
        *
        * @param    domainName
        *           The value of the DOMAIN-NAME attribute.
        */
       @LegacyAttribute(name = "DOMAIN-NAME", setter = true)
       public void setDomainName(String domainName);

       /**
        * Get the DOMAIN-DESCRIPTION attribute.
        *
        * @return   See above.
        */
       @LegacyAttribute(name = "DOMAIN-DESCRIPTION")
       public character getDomainDescription();

       /**
        * Set the DOMAIN-DESCRIPTION Attribute.
        *
        * @param    desc
        *           The value of the DOMAIN-DESCRIPTION attribute.
        */
       @LegacyAttribute(name = "DOMAIN-DESCRIPTION", setter = true)
       public void setDomainDescription(String desc);

       /**
        * Set the DOMAIN-DESCRIPTION Attribute.
        *
        * @param    desc
        *           The value of the DOMAIN-DESCRIPTION attribute.
        */
       @LegacyAttribute(name = "DOMAIN-DESCRIPTION", setter = true)
       public void setDomainDescription(character desc);

       /**
        * Get the CLIENT-TTY attribute.
        *
        * @return   See above.
        */
       @LegacyAttribute(name = "CLIENT-TTY")
       public character getClientTty();

       /**
        * Set the CLIENT-TTY Attribute.
        *
        * @param    tty
        *           The value of the CLIENT-TTY attribute.
        */
       @LegacyAttribute(name = "CLIENT-TTY", setter = true)
       public void setClientTty(String tty);

       /**
        * Set the CLIENT-TTY Attribute.
        *
        * @param    tty
        *           The value of the CLIENT-TTY attribute.
        */
       @LegacyAttribute(name = "CLIENT-TTY", setter = true)
       public void setClientTty(character tty);

       /**
        * Get the CLIENT-WORKSTATION attribute.
        *
        * @return   See above.
        */
       @LegacyAttribute(name = "CLIENT-WORKSTATION")
       public character getClientWks();

       /**
        * Set the CLIENT-WORKSTATION Attribute.
        *
        * @param    wks
        *           The value of the CLIENT-WORKSTATION attribute.
        */
       @LegacyAttribute(name = "CLIENT-WORKSTATION", setter = true)
       public void setClientWks(String wks);

       /**
        * Set the CLIENT-WORKSTATION Attribute.
        *
        * @param    wks
        *           The value of the CLIENT-WORKSTATION attribute.
        */
       @LegacyAttribute(name = "CLIENT-WORKSTATION", setter = true)
       public void setClientWks(character wks);

       /**
        * Get the AUDIT-EVENT-CONTEXT attribute.
        *
        * @return   See above.
        */
       @LegacyAttribute(name = "AUDIT-EVENT-CONTEXT")
       public character getAuditEventContext();

       /**
        * Set the AUDIT-EVENT-CONTEXT Attribute.
        *
        * @param    ctx
        *           The value of the AUDIT-EVENT-CONTEXT attribute.
        */
       @LegacyAttribute(name = "AUDIT-EVENT-CONTEXT", setter = true)
       public void setAuditEventContext(String ctx);

       /**
        * Set the AUDIT-EVENT-CONTEXT Attribute.
        *
        * @param    ctx
        *           The value of the AUDIT-EVENT-CONTEXT attribute.
        */
       @LegacyAttribute(name = "AUDIT-EVENT-CONTEXT", setter = true)
       public void setAuditEventContext(character ctx);

       /**
        * Get the LOGIN-HOST attribute.
        *
        * @return   See above.
        */
       @LegacyAttribute(name = "LOGIN-HOST")
       public character getLoginHost();

       /**
        * Set the LOGIN-HOST Attribute.
        *
        * @param    host
        *           The value of the LOGIN-HOST attribute.
        */
       @LegacyAttribute(name = "LOGIN-HOST", setter = true)
       public void setLoginHost(String host);

       /**
        * Set the LOGIN-HOST Attribute.
        *
        * @param    host
        *           The value of the LOGIN-HOST attribute.
        */
       @LegacyAttribute(name = "LOGIN-HOST", setter = true)
       public void setLoginHost(character host);

       /**
        * Get the ROLES attribute.
        *
        * @return   See above.
        */
       @LegacyAttribute(name = "ROLES")
       public character getRoles();

       /**
        * Set the ROLES Attribute.
        *
        * @param    roles
        *           The value of the ROLES attribute.
        */
       @LegacyAttribute(name = "ROLES", setter = true)
       public void setRoles(String roles);

       /**
        * Set the ROLES Attribute.
        *
        * @param    roles
        *           The value of the ROLES attribute.
        */
       @LegacyAttribute(name = "ROLES", setter = true)
       public void setRoles(character roles);

       /**
        * Get the LOGIN-STATE attribute.
        *
        * @return   A character value that represents the current state of the
        *           client-principal object.
        */
       @LegacyAttribute(name = "LOGIN-STATE")
       public character getLoginState();

       /**
        * Get the LOGIN-EXPIRATION-TIMESTAMP attribute.
        *
        * @return   The time stamp specifying when the client-principal object will expire
        *           client-principal object.
        */
       @LegacyAttribute(name = "LOGIN-EXPIRATION-TIMESTAMP")
       public datetimetz getLoginExpirationTimestamp();

       /**
        * Get the LOGIN-EXPIRATION-TIMESTAMP attribute.
        *
        * @param    ts
        *           The time stamp specifying when the client-principal object will expire
        *           client-principal object.
        */
       @LegacyAttribute(name = "LOGIN-EXPIRATION-TIMESTAMP", setter = true)
       public void setLoginExpirationTimestamp(datetimetz ts);

       /**
        * Get the SEAL-TIMESTAMP attribute.
        *
        * @return   The time stamp (as a DATETIME-TZ value) for when the client-principal
        *           object was sealed in the LOGIN state
        */
       @LegacyAttribute(name = "SEAL-TIMESTAMP")
       public datetimetz getSealTimestamp();

       /**
        * Get the PRIMARY-PASSPHRASE attribute.
        * Always returns error
        *
        * @return null
        */
       @LegacyAttribute(name = "PRIMARY-PASSPHRASE")
       public character getPrimaryPassphrase();

       /**
        * Get the PRIMARY-PASSPHRASE attribute value (for internal use).
        *
        * @return PRIMARY-PASSPHRASE attribute value.
        */
       public character primaryPassphrase();
       /**
        * Set the PRIMARY-PASSPHRASE attribute.
        *
        * @param passphrase
        *        new value of the attribute
        */
       @LegacyAttribute(name = "PRIMARY-PASSPHRASE", setter = true)
       public void setPrimaryPassphrase(String passphrase);

       /**
        * Set the PRIMARY-PASSPHRASE attribute.
        *
        * @param passphrase
        *        new value of the attribute
        */
       @LegacyAttribute(name = "PRIMARY-PASSPHRASE", setter = true)
       public void setPrimaryPassphrase(character passphrase);

       /**
        * Get the QUALIFIED-USER-ID attribute.
        *
        * @return the value of the attrubute
        */
       @LegacyAttribute(name = "QUALIFIED-USER-ID")
       public character getQualifiedUid();

       /**
        * Set the QUALIFIED-USER-ID attribute.
        *
        * @param uid
        *        new value of the attribute
        */
       @LegacyAttribute(name = "QUALIFIED-USER-ID", setter = true)
       public void setQualifiedUid(String uid);

       /**
        * Set the QUALIFIED-USER-ID attribute.
        *
        * @param uid
        *        new value of the attribute
        */
       @LegacyAttribute(name = "QUALIFIED-USER-ID", setter = true)
       public void setQualifiedUid(character uid);

       /**
        * Set the STATE-DETAIL attribute.
        *
        * @return the value of the attrubute
       */
       @LegacyAttribute(name = "STATE-DETAIL")
       public character getStateDetail();

       /**
        * Get a comma-separated list of logical database names that is stored in the
        * client-principal object
        *
        * @return a comma-separated list of logical database names
        */
       @LegacyAttribute(name = "DB-LIST")
       public character getDbList();

       /**
        * Set this property in the CLIENT-PRINCIPAL object.
        *
        * @param    prop
        *           The property's name.
        * @param    val
        *           The property's value.
        *
        * @return   <code>true</code> if the property could be set.
        */
       @LegacyMethod(name = "SET-PROPERTY")
       public logical setProperty(character prop, character val);

       /**
        * Set this property in the CLIENT-PRINCIPAL object.
        *
        * @param    prop
        *           The property's name.
        * @param    val
        *           The property's value.
        *
        * @return   <code>true</code> if the property could be set.
        */
       @LegacyMethod(name = "SET-PROPERTY")
       public logical setProperty(character prop, String val);

       /**
        * Set this property in the CLIENT-PRINCIPAL object.
        *
        * @param    prop
        *           The property's name.
        * @param    val
        *           The property's value.
        *
        * @return   <code>true</code> if the property could be set.
        */
       @LegacyMethod(name = "SET-PROPERTY")
       public logical setProperty(String prop, character val);

       /**
        * Set this property in the CLIENT-PRINCIPAL object.
        *
        * @param    prop
        *           The property's name.
        * @param    val
        *           The property's value.
        *
        * @return   <code>true</code> if the property could be set.
        */
       @LegacyMethod(name = "SET-PROPERTY")
       public logical setProperty(String prop, String val);

       /**
        * Get a list of all application-defined properties stored in the client-principal object.
        *
        * @return   Returns a comma-separated list of all application-defined properties stored in
        *           the client-principal object
        */
       @LegacyMethod(name = "LIST-PROPERTY-NAMES")
       public character listPropertyNames();

       /**
        * Get the value of the specified property, from the CLIENT-PRINCIPAL object.
        *
        * @param    prop
        *           The property's name.
        *
        * @return   The property's value.
        */
       @LegacyMethod(name = "GET-PROPERTY")
       public character getProperty(character prop);

       /**
        * Get the value of the specified property, from the CLIENT-PRINCIPAL object.
        *
        * @param    prop
        *           The property's name.
        *
        * @return   The property's value.
        */
       @LegacyMethod(name = "GET-PROPERTY")
       public character getProperty(String prop);

       /**
        * Export the state of this CLIENT-PRINCIPAL object to a byte representation.
        *
        * @return   The byte representation as a {@link raw} instance.
        */
       @LegacyMethod(name = "EXPORT-PRINCIPAL")
       public raw exportPrincipal();

       /**
        * Import the state of this CLIENT-PRINCIPAL object from the specified byte representation.
        *
        * @param    data
        *           The byte representation.
        *
        * @return   <code>true</code> id successful
        */
       @LegacyMethod(name = "IMPORT-PRINCIPAL")
       public logical importPrincipal(raw data);

       /**
        * Retrieves the tenant ID associated with the client-principal object.
        *
        * @return   The tenant ID as an integer.
        */
       @LegacyMethod(name = "TENANT-ID")
       public integer tenantId();

       /**
        * Retrieves the tenant ID associated with the user identity sealed in the client-principal
        * and assigned to a connection to the specified multi-tenant database.
        *
        * @param    dbExp
        *           The database expression specifying the multi-tenant database connection.
        *
        * @return   The tenant ID as an integer.
        */
       @LegacyMethod(name = "TENANT-ID")
       public integer tenantId(character dbExp);

       /**
        * Retrieves the tenant name associated with the client-principal object.
        *
        * @return   The tenant name.
        */
       @LegacyMethod(name = "TENANT-NAME")
       public character tenantName();

       /**
        * Retrieves the tenant name associated with the user identity sealed in the client-principal
        * and assigned to a connection to the specified multi-tenant database.
        *
        * @param    dbExp
        *           The database expression specifying the multi-tenant database connection.
        *
        * @return   The tenant name.
        */
       @LegacyMethod(name = "TENANT-NAME")
       public character tenantName(character dbExp);

       /**
        * Seal this CLIENT-PRINCIPAL, using the given domain access code.
        *
        * @param    domainAccessCode
        *           The access code.
        *
        * @return   <code>true</code> id successful
        */
       @LegacyMethod(name = "SEAL")
       public logical seal(character domainAccessCode);

       /**
        * Seal this CLIENT-PRINCIPAL, using the given domain access code, for internal use.
        *
        * @param domainAccessCode
        *        The access code.
        * @param callee
        *        the method callee.
        *
        * @return   <code>true</code> id successful.
        */
       public logical seal(String domainAccessCode, SealCallee callee);

       /**
        * Seal this CLIENT-PRINCIPAL, using the given domain access code.
        *
        * @param    domainAccessCode
        *           The access code.
        *
        * @return   <code>true</code> id successful
        */
       @LegacyMethod(name = "SEAL")
       public logical seal(String domainAccessCode);

       /**
        * Check if this CLIENT-PRINCIPIAL has been sealed.
        *
        * @return   The sealed state.
        */
       public boolean isSealed();

       /**
        * Indicates that the identity asserted in the unsealed client-principal object cannot be
        * authenticated.
        *
        * @return   <code>true</code> id successful
        */
       @LegacyMethod(name = "AUTHENTICATION-FAILED")
       public logical authenticationFailed();

       /**
        * Indicates that the identity asserted in the unsealed client-principal object cannot be
        * authenticated.
        *
        * @param    reason
        *           An optional character expression that specifies the reason for the authentication
        *           failure.
        *
        * @return   <code>true</code> id successful
        */
       @LegacyMethod(name = "AUTHENTICATION-FAILED")
       public logical authenticationFailed(character reason);

       /**
        * Indicates that the identity asserted in the unsealed client-principal object cannot be
        * authenticated.
        *
        * @param    reason
        *           An optional character expression that specifies the reason for the authentication
        *           failure.
        * @param    fromSetClient
        *           flag indicating that called from SET-CLIENT.
        *
        * @return   <code>true</code> id successful.
        */
       public logical authenticationFailed(character reason, boolean fromSetClient);
       /**
        * Indicates that the identity asserted in the unsealed client-principal object cannot be
        * authenticated.
        *
        * @param    reason
        *           An optional character expression that specifies the reason for the authentication
        *           failure.
        *
        * @return   <code>true</code> id successful
        */
       @LegacyMethod(name = "AUTHENTICATION-FAILED")
       public logical authenticationFailed(String reason);

       /**
        * Indicates that the identity asserted in the unsealed client-principal object cannot be
        * authenticated.
        *
        * @param    reason
        *           An optional character expression that specifies the reason for the authentication
        *           failure.
        * @param    fromSetClient
        *           flag indicating that called from SET-CLIENT.
        *
        * @return   <code>true</code> id successful.
        */
       public logical authenticationFailed(String reason, boolean fromSetClient);

       /**
        * Validates the message authentication code (MAC) generated by the SEAL( ) method to seal a
        * client-principal object.
        *
        * @return   <code>true</code> id successful
        */
       @LegacyMethod(name = "VALIDATE-SEAL")
       public logical validateSeal();

       /**
        * Validates the message authentication code (MAC) generated by the SEAL( ) method to seal a
        * client-principal object.
        *
        * @param    domainAccessCode
        *           The access code.
        *
        * @return   <code>true</code> id successful
        */
       @LegacyMethod(name = "VALIDATE-SEAL")
       public logical validateSeal(String domainAccessCode);

       /**
        * Validates the message authentication code (MAC) generated by the SEAL( ) method to seal a
        * client-principal object.
        *
        * @param    domainAccessCode
        *           The access code.
        *
        * @return   <code>true</code> id successful
        */
       @LegacyMethod(name = "VALIDATE-SEAL")
       public logical validateSeal(character domainAccessCode);

       /**
        * Indicates that the user represented by the sealed client-principal object (in the LOGIN
        * state) has logged out of their current user login session.
        *
        * @return   <code>true</code> id successful
        */
       @LegacyMethod(name = "LOGOUT")
       public logical logout();

       /**
        * Simplifies initialization of client-principal object attributes that are required and
        * commonly used
        *
        * @param qualifiedUid
        *         A character expression that evaluates to a fully qualified user ID (user name and
        *         domain name delimited by the '@' character)
        *
        * @return <code>true</code> on success
        */
       @LegacyMethod(name = "INITIALIZE")
       public logical initialize(character qualifiedUid);

       /**
        * Simplifies initialization of client-principal object attributes that are required and
        * commonly used
        *
        * @param qualifiedUid
        *         A character expression that evaluates to a fully qualified user ID (user name and
        *         domain name delimited by the '@' character)
        * @param sessionId
        *        An optional character expression that evaluates to the user's application login session ID.
        *
        * @return <code>true</code> on success
        */
       @LegacyMethod(name = "INITIALIZE")
       public logical initialize(character qualifiedUid, character sessionId);

       /**
        *
        * @param qualifiedUid
        *         A character expression that evaluates to a fully qualified user ID (user name and
        *         domain name delimited by the '@' character)
        * @param sessionId
        *        An optional character expression that evaluates to the user's application login
        *        session ID.
        * @param expriration
        *        An optional DATETIME-TZ expression that evaluates to a date and time value that
        *        specifies the expiration of thee client-principal user credentials
        *
        * @return <code>true</code> on success
        */
       @LegacyMethod(name = "INITIALIZE")
       public logical initialize(character qualifiedUid, character sessionId,
             BaseDataType expriration);

       /**
        * Simplifies initialization of client-principal object attributes that are required and
        * commonly used
        *
        * @param qualifiedUid
        *         A character expression that evaluates to a fully qualified user ID (user name and
        *         domain name delimited by the '@' character)
        * @param sessionId
        *        An optional character expression that evaluates to the user's application login
        *        session ID.
        * @param expriration
        *        An optional DATETIME-TZ expression that evaluates to a date and time value that
        *        specifies the expiration of thee client-principal user credentials
        * @param primaryPassphrase
        *        An optional character expression that evaluates to the cleartext or encrypted value
        *        of the user's account password.
        *
        * @return <code>true</code> on success
        */
       @LegacyMethod(name = "INITIALIZE")
       public logical initialize(character qualifiedUid, character sessionId,
             BaseDataType expriration, character primaryPassphrase);

       /**
        * Validate CLIENT-PRINCIPAL against domain password.
        *
        * @param where
        *        subsystem name
        * @param dac
        *        domain access code
        * @param password
        *        domain password
        * @param callee
        *        where the method is called from
        *
        * @return <code>true</code> if successful
        */
       public logical validatePassword(String where, String dac, String password, SealCallee callee);

      /**
       * Validate CLIENT-PRINCIPAL against domain access code.
       *
       * @param dac
       *        domain access code
       * @param where
       *        subsystem name
       * @param callee
       *        where the method is called from
       *
       * @return <code>true</code> if successful
       */
      public logical validateDomainAccessCode(String where, String dac, SealCallee callee);

      /**
       * Get the SEAL operation failure reason.
       *
       * @return SEAL operation failure reason.
       */
      public SealFailure sealFailure();

      /**
       * Enumeration encoding the callee of the SEAL method.
       *
       */
      public static enum SealCallee
      {
         /** called from the 4GL code. */
         APP,
         /** called from the SET-CLIENT. */
         SET_CLIENT,
         /** called from the SET-DB-CLIENT. */
         SET_DB_CLIENT
      }

      /**
       * Enumeration encoding the reasons for the SEAL failure.
       *
       */
      public static enum SealFailure
      {
         /** missing required attributes. */
         MISSING_ATTRIBUTES,
         /** invalid state. */
         INVALID_STATE,
         /** expired. */
         EXPIRED
      }
    }