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
}
}