org.example.azapi
Interface AzEntity<T extends java.lang.Enum<T> & AzCategoryId>


public interface AzEntity<T extends java.lang.Enum<T> & AzCategoryId>

The AzEntity Interface represents a XACML collection of attributes. This is a generic interface that is used as the basis for holding collections of attributes where they appear in both the AzRequestContext and AzResponseContext.

The AzEntity Interface also contains factory methods for creating AzAttributes that will be directly added the current AzEntity object. It also contains factory methods for creating the AzAttributeValue objects with the associated XACML AzDataTypeId datatypes and the related Java or AzData* objects used to create the XACML datatypes.

AzEntity is also is used to hold the collections of attributes that are returned in the AzResponseContext (AzStatusDetail for a collection of missing attributes reported by the PDP, and AzObligation, which contains a set of AzAttributes that are used to inform the PEP of responsibilities associated with processing the Results of an authorization request.

Basically, in the XACML model, there are four "categories" of entities defined that are part of a XACML Request, each of which can contain a collection of attributes:

In addition, the XACML model identifies four other kinds of "Subject" entities that are represented each by their own AzCategoryId Enum, which can appear in any request, and in any number for multiple decision requests: Note: for the AzEntity objects with AzCategoryId Enum equal to one of the above, only AzAttributes with that same AzCategoryId Enum are allowed in the collection. i.e. the AzEntity and all the contained AzAttributes have the same AzCategoryId Enum with no exceptions. This collection may be accessed via the getAzAttributeSet() method.

Note: for AzEntity objects with AzCategoryId Enum equal to one of the following below, the collection may contain any AzAttribute with any AzCategoryId Enum. This collection may be accessed via the getAzAttributeMixedSet() method.

There are two "categories" of entities that contain a collection of mixed AzAttributes that are returned by the PDP in a XACML Response element:

TBD: there are other "categories" as well in XACML, for example in the RBAC Profile and the Delegation profile for XACML 3.0. How and whether to incorporate those categories to AzApi is an open issue.

TBD: should the createAzAttributeValue methods throw Exceptions based on processing the input values, or can it be assumed the object containing the input value has already handled any exception conditions?


Method Summary
<V extends java.lang.Enum<V> & AzCategoryId>
boolean
addAzAttribute(AzAttribute<V> azAttribute)
          Add an existing AzAttribute to the current collection of AzAttributes in this AzEntity object.
<U extends java.lang.Enum<U> & AzDataTypeId,V,W extends java.lang.Enum<W> & AzCategoryId>
boolean
addAzAttribute(W w, java.lang.String issuer, java.lang.String attributeId, AzAttributeValue<U,V> attributeValue)
          Add a new AzAttribute to the current collection of AzAttributes in this AzEntity object.
<U extends java.lang.Enum<U> & AzDataTypeId,V>
AzAttribute<T>
createAzAttribute(java.lang.String issuer, java.lang.String attributeId, AzAttributeValue<U,V> attributeValue)
          Creates a general AzAttribute with the AzCategoryId Enum, T, specified for this AzEntity object, and add it to the Set> managed by this AzEntity object.
 AzAttributeValueAnyURI createAzAttributeValue(AzDataTypeIdAnyURI u, java.net.URI v)
          Returns an AzAttributeValue object that holds a #anyURI type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueBase64Binary createAzAttributeValue(AzDataTypeIdBase64Binary u, AzDataByteArray v)
          Returns an AzAttributeValue object that holds a AzDataByteArray type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueBoolean createAzAttributeValue(AzDataTypeIdBoolean u, java.lang.Boolean v)
          Returns an AzAttributeValue object that holds a Boolean type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueDate createAzAttributeValue(AzDataTypeIdDate u, AzDataDateTime v)
          Returns a general AzAttributeValueDate object that holds a #date type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueDateTime createAzAttributeValue(AzDataTypeIdDateTime u, AzDataDateTime v)
          Returns a general AzAttributeValueDateTime object that holds a #dateTime type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueDayTimeDuration createAzAttributeValue(AzDataTypeIdDayTimeDuration u, AzDataDayTimeDuration v)
          Returns an AzAttributeValueDayTimeDuration object that holds a XACML #dayTimeDuration DataType.
 AzAttributeValueDnsName createAzAttributeValue(AzDataTypeIdDnsName u, java.lang.String v)
          Returns an AzAttributeValue object that holds a String type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueDouble createAzAttributeValue(AzDataTypeIdDouble u, java.lang.Double v)
          Returns an AzAttributeValue object that holds a Double type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueHexBinary createAzAttributeValue(AzDataTypeIdHexBinary u, AzDataByteArray v)
          Returns an AzAttributeValue object that holds a AzDataByteArray type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueInteger createAzAttributeValue(AzDataTypeIdInteger u, java.lang.Long v)
          Returns an AzAttributeValue object that holds an Integer type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueIpAddress createAzAttributeValue(AzDataTypeIdIpAddress u, java.lang.String v)
          Returns an AzAttributeValue object that holds a String type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueRfc822Name createAzAttributeValue(AzDataTypeIdRfc822Name u, java.lang.String v)
          Returns an AzAttributeValue object that holds a String type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueString createAzAttributeValue(AzDataTypeIdString u, java.lang.String v)
          Returns an AzAttributeValue object that holds a String type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueTime createAzAttributeValue(AzDataTypeIdTime u, AzDataDateTime v)
          Returns an AzAttributeValueTime object that holds a #time type and value, where that value was established by the parameters passed in this method.
 AzAttributeValueX500Name createAzAttributeValue(AzDataTypeIdX500Name u, javax.security.auth.x500.X500Principal v)
          Returns an AzAttributeValue object that holds a #x500Name type and value, that can be used with an AzAttribute of any AzCategoryId.
 AzAttributeValueYearMonthDuration createAzAttributeValue(AzDataTypeIdYearMonthDuration u, AzDataYearMonthDuration v)
          Returns an AzAttributeValueYearMonthDuration object that holds a XACML #yearMonthDuration DataType.
 AzDataByteArray createAzDataByteArray(byte[] byteArray)
          Returns a helper data container for boxed Java byte[] arrays
 AzDataDateTime createAzDataDateTime(java.util.Date date, int actualTimeZone, int intendedTimeZone, int nanoSeconds)
          Returns a helper data container for XACML #date, #time, and #date-time datatypes
 AzDataDayTimeDuration createAzDataDayTimeDuration(boolean isNegativeDuration, long days, long hours, long minutes, long seconds, int nanoSeconds)
          Returns a helper data container for XACML #dayTimeDuration DataType
 AzDataYearMonthDuration createAzDataYearMonthDuration(boolean isNegativeDuration, long years, long months)
          Returns a helper data container for Xacml #yearMonthDuration
 AzAttribute<T> getAttributeByAttribId(java.lang.String s)
          Get any attribute in the current collection by specifying its AttributeId.
 java.util.Set<AzAttribute<?>> getAzAttributeMixedSet()
          Get the Set that holds the attributes in this collection
 java.util.Set<AzAttribute<T>> getAzAttributeSet()
          Get the Set that holds the attributes in this collection
 java.util.Set<AzAttribute<T>> getAzAttributeSetByAttribId(java.lang.String s)
          Get the Set of attributes in this collection that match the provided XACML AttributeId.
 T getAzCategoryId()
          Returns the AzCategoryId of this AzEntity.
 java.lang.String getId()
          Get a local non-XACML implementation-specific id that can be used to distinguish this AzEntity object from other AzEntity objects.
 

Method Detail

getAzCategoryId

T getAzCategoryId()
Returns the AzCategoryId of this AzEntity. Depending on the specific subclass, this AzCategoryId may or may not govern the AzCategoryId of the member attributes.

Generally, for the AzRequestContext collections, this AzCategoryId specifies the allowed AzCategoryId for the member attributes. For the AzResponseContext collections (AzObligation, AZStatusDetail) this AzCategoryId only indicates the type of collection, and the member attributes can have any AzCategoryId.

Returns:
an Enum that implements AzCategoryId

getId

java.lang.String getId()
Get a local non-XACML implementation-specific id that can be used to distinguish this AzEntity object from other AzEntity objects. This is primarily intended to be an id used for operations personnel to assist in identifying AzEntity objects.

An alternative approach might be to have specific "official" AzAttributes used for such purposes. XACML provides ids, such as subject-id, resource-id, and action-id, however, these ids are tied to somewhat to XACML semantics, and enterprises may want to define a specific id which could be applied in any category, possibly category-specific, which could be used to correlate the entities in the authorization requests for administrative purposes. The id provided by this method could be used to access the "special id" if it existed within the attribute collection or it could be implemented independently of the attributes as well.

Returns:
a String containing an identifier associated with this AzEntity object.
See Also:
AzXacmlStrings.X_ATTR_ACTION_ID

createAzAttribute

<U extends java.lang.Enum<U> & AzDataTypeId,V> AzAttribute<T> createAzAttribute(java.lang.String issuer,
                                                                               java.lang.String attributeId,
                                                                               AzAttributeValue<U,V> attributeValue)
Creates a general AzAttribute with the AzCategoryId Enum, T, specified for this AzEntity object, and add it to the Set> managed by this AzEntity object.

The AzApi caller must provide an optional issuer, a required AttributeId, and a required AzAttributeValue containing an AzDataTypeId Enum identifying the XACML datatype of this attribute, and a value for this attribute in an appropriate object, determined by the createAzAttributeValue(U,V) signature, where U is the XACML datatype, and V is the corresponding object type required to provide the value for an attribute of that XACML datatype.

When an attribute is created within an AzEntity object, it inherits the AzCategoryId Enum from the AzEntity object.

Parameters:
issuer -
attributeId -
attributeValue -
Returns:
a new AzAttribute representing category, issuer, attributeId, and attributeValue provided

getAttributeByAttribId

AzAttribute<T> getAttributeByAttribId(java.lang.String s)
Get any attribute in the current collection by specifying its AttributeId.

Note: In the case where an attribute is multi-valued, this method returns only one of the values, and which value may vary if the method is called multiple times. Therefore, if the AzApi caller needs information whether there are additional values, and what those values are, then the method getAzAttributeSetByAttribId(String s) should be used, which returns all the values with a specific XACML AttributeId.

Parameters:
s - a String containing a XACML AttributeId
Returns:
any AzAttribute from this AzEntity object that matches the current XACML AttributeId
See Also:
getAzAttributeSetByAttribId(String)

getAzAttributeSetByAttribId

java.util.Set<AzAttribute<T>> getAzAttributeSetByAttribId(java.lang.String s)
Get the Set of attributes in this collection that match the provided XACML AttributeId.

In general, XACML attributes may be multi-valued. The way this is represented by AzApi is that a separate AzAttribute instance exists for each value.

Parameters:
s - a String containing the XACML AttributeId being requested
Returns:
the Set of AzAttributes that have an AttributeId that matches the String provided.

getAzAttributeSet

java.util.Set<AzAttribute<T>> getAzAttributeSet()
Get the Set that holds the attributes in this collection

Note: this method returns a Set> that contains only AzAttributes with the AzCategoryId Enum designated for this AzEntity object.

Returns:
a SetAzAttribute which may be empty or contain one or more AzAttributes; null if this AzEntity has only mixed attributes

getAzAttributeMixedSet

java.util.Set<AzAttribute<?>> getAzAttributeMixedSet()
Get the Set that holds the attributes in this collection

Note: this method returns a Set> that contains AzAttributes that may individually have any AzCategoryId Enum, which may be the same as or different from the AzCategory Enum designated for this AzEntity object.

Note: A specific AzEntity may have AzAttributes either in the mixed attribute collection or the uniform attribute collection but not both. The "other" collection will always be null.

Returns:
a SetAzAttribute which may be empty or contain one or more AzAttributes; null if this AzEntity has only uniform attributes

addAzAttribute

<V extends java.lang.Enum<V> & AzCategoryId> boolean addAzAttribute(AzAttribute<V> azAttribute)
Add an existing AzAttribute to the current collection of AzAttributes in this AzEntity object.

For most AzEntity objects the AzCategoryId Enum, V, must match that of the AzEntity.getAzCategoryId(), T. However, for AzEntity and AzEntity, AzAttributes of any category are allowed in the collection.

Type Parameters:
V - the AzCategoryId Enum of azAttribute
Parameters:
azAttribute -
Returns:
a boolean true if azAttribute added, false if not
See Also:
AzEntity<AzCategoryIdObligation>
AzEntity<AzCategoryIdStatusDetail>

addAzAttribute

<U extends java.lang.Enum<U> & AzDataTypeId,V,W extends java.lang.Enum<W> & AzCategoryId> boolean addAzAttribute(W w,
                                                                                                               java.lang.String issuer,
                                                                                                               java.lang.String attributeId,
                                                                                                               AzAttributeValue<U,V> attributeValue)
Add a new AzAttribute to the current collection of AzAttributes in this AzEntity object.

For most AzEntity objects the AzCategoryId Enum, W, must match that of the AzEntity.getAzCategoryId(). However, for AzEntity and AzEntity, AzAttributes of any category are allowed.

Type Parameters:
U - A Java type containing the value of the attribute
V - An AzDataTypeId Enum representing a XACML DataType
W - An AzCategoryId Enum representing a XACML Category
Parameters:
w - an instance of W
issuer - a String identifying the Issuer of this attribute
attributeId -
attributeValue - an AzAttributeValue
Returns:
boolean true if attribute added, false if not

createAzAttributeValue

AzAttributeValueAnyURI createAzAttributeValue(AzDataTypeIdAnyURI u,
                                              java.net.URI v)
Returns an AzAttributeValue object that holds a #anyURI type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdAnyURI Enum
v - a URI providing a value for this AzAttributeValue object
Returns:
See Also:
AzAttributeValueAnyURI
AzAttributeValue
See Also:
createAzAttribute(String, String, AzAttributeValue)

createAzAttributeValue

AzAttributeValueBase64Binary createAzAttributeValue(AzDataTypeIdBase64Binary u,
                                                    AzDataByteArray v)
Returns an AzAttributeValue object that holds a AzDataByteArray type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdBase64Binary Enum
v - an AzDataByteArray containing the Base64 binary data
Returns:
a new AzAttributeValueBase64Binary representing the Base64 binary data provided in the AzDataByteArray
See Also:
AzAttributeValueBase64Binary, AzAttributeValue

createAzAttributeValue

AzAttributeValueBoolean createAzAttributeValue(AzDataTypeIdBoolean u,
                                               java.lang.Boolean v)
Returns an AzAttributeValue object that holds a Boolean type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdBoolean Enum
v - a Boolean with the value that will be set for this attribute
Returns:
a new AzAttributeValueBoolean representing the Boolean value provided
See Also:
AzAttributeValueBoolean, AzAttributeValue

createAzAttributeValue

AzAttributeValueDate createAzAttributeValue(AzDataTypeIdDate u,
                                            AzDataDateTime v)
Returns a general AzAttributeValueDate object that holds a #date type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdDate Enum
v - an AzDataDateTime object containing the value provided for this attribute
Returns:
an AzAttributeValueDate instance representing the value provided for this attribute
See Also:
AzAttributeValueDate

createAzAttributeValue

AzAttributeValueDateTime createAzAttributeValue(AzDataTypeIdDateTime u,
                                                AzDataDateTime v)
Returns a general AzAttributeValueDateTime object that holds a #dateTime type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdDateTime Enum
v - an AzDataDateTime object containing the value provided
Returns:
an AzAttributeValueDateTime instance representing the value provided
See Also:
AzAttributeValueDateTime

createAzAttributeValue

AzAttributeValueDayTimeDuration createAzAttributeValue(AzDataTypeIdDayTimeDuration u,
                                                       AzDataDayTimeDuration v)
Returns an AzAttributeValueDayTimeDuration object that holds a XACML #dayTimeDuration DataType.

Parameters:
u - an AzDataTypeIdDayTimeDuration Enum
v - an AzDataDayTimeDuration object providing a value
Returns:
an AzAttributeValueDayTimeDuration representing the provided value.

createAzAttributeValue

AzAttributeValueDnsName createAzAttributeValue(AzDataTypeIdDnsName u,
                                               java.lang.String v)
Returns an AzAttributeValue object that holds a String type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdDnsName Enum
v - a String providing the value for this AzAttributeValue object
Returns:
an AzAttributeValueDnsName representing the value provided
See Also:
AzAttributeValueDnsName, AzAttributeValue

createAzAttributeValue

AzAttributeValueDouble createAzAttributeValue(AzDataTypeIdDouble u,
                                              java.lang.Double v)
Returns an AzAttributeValue object that holds a Double type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdDouble Enum
v - a Double providing the value for this AzAttributeValue object
Returns:
an AzAttributeValueDouble representing the value provided
See Also:
AzAttributeValueDouble, AzAttributeValue

createAzAttributeValue

AzAttributeValueHexBinary createAzAttributeValue(AzDataTypeIdHexBinary u,
                                                 AzDataByteArray v)
Returns an AzAttributeValue object that holds a AzDataByteArray type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdHexBinary Enum
v - an AzDataByteArray containing binary data
Returns:
a new AzAttributeValueHexBinary representing the binary data provided in the AzDataByteArray
See Also:
AzAttributeValueHexBinary, AzAttributeValue

createAzAttributeValue

AzAttributeValueInteger createAzAttributeValue(AzDataTypeIdInteger u,
                                               java.lang.Long v)
Returns an AzAttributeValue object that holds an Integer type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdInteger Enum
v - a Long containing an integer
Returns:
a new AzAttributeValueInteger representing the value of the integer provided.
See Also:
AzAttributeValueInteger, AzAttributeValue

createAzAttributeValue

AzAttributeValueIpAddress createAzAttributeValue(AzDataTypeIdIpAddress u,
                                                 java.lang.String v)
Returns an AzAttributeValue object that holds a String type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdIpAddress Enum
v - a String value provided to be used to create the IpAddress
Returns:
a new AzAttributeValueIpAddress representing the value of the String provided
See Also:
AzAttributeValueIpAddress, AzAttributeValue

createAzAttributeValue

AzAttributeValueRfc822Name createAzAttributeValue(AzDataTypeIdRfc822Name u,
                                                  java.lang.String v)
Returns an AzAttributeValue object that holds a String type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdRfc822Name Enum
v - a String value representing an RFC822 name
Returns:
a new AzAttributeValueRfc822Name representing the String value provided
See Also:
AzAttributeValueRfc822Name, AzAttributeValue

createAzAttributeValue

AzAttributeValueString createAzAttributeValue(AzDataTypeIdString u,
                                              java.lang.String v)
Returns an AzAttributeValue object that holds a String type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDateTypeIdString Enum
v - a String value
Returns:
a new AzAttributeValueString object representing the String value provided.
See Also:
AzAttributeValueString, AzAttributeValue

createAzAttributeValue

AzAttributeValueTime createAzAttributeValue(AzDataTypeIdTime u,
                                            AzDataDateTime v)
Returns an AzAttributeValueTime object that holds a #time type and value, where that value was established by the parameters passed in this method. that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDateTypeIdTime Enum
v - an AzDataDateTime object
Returns:
an AzAttributeValueTime instance representing the parameters provided in the AzDataDateTime object provided
See Also:
AzAttributeValueTime

createAzAttributeValue

AzAttributeValueX500Name createAzAttributeValue(AzDataTypeIdX500Name u,
                                                javax.security.auth.x500.X500Principal v)
Returns an AzAttributeValue object that holds a #x500Name type and value, that can be used with an AzAttribute of any AzCategoryId.

Parameters:
u - an AzDataTypeIdX500Name Enum
v - an X500Principal object
Returns:
anew AzAttributeValueX500Name representing the X500Principal provided
See Also:
AzAttributeValueX500Name, AzAttributeValue

createAzAttributeValue

AzAttributeValueYearMonthDuration createAzAttributeValue(AzDataTypeIdYearMonthDuration u,
                                                         AzDataYearMonthDuration v)
Returns an AzAttributeValueYearMonthDuration object that holds a XACML #yearMonthDuration DataType.

Parameters:
u - an AzDataTypeIdYearMonthDuration Enum
v - an AzDataYearMonthDuration object providing the duration data to be used for the value
Returns:
an AzAttributeValueYearMonthDuration

createAzDataDateTime

AzDataDateTime createAzDataDateTime(java.util.Date date,
                                    int actualTimeZone,
                                    int intendedTimeZone,
                                    int nanoSeconds)
Returns a helper data container for XACML #date, #time, and #date-time datatypes

Parameters:
date -
actualTimeZone -
intendedTimeZone -
nanoSeconds -
Returns:
an AzDataDateTime that can be used as input to creating Date and Time AzAttributeValues
See Also:
AzAttributeValueDate, AzAttributeValueDateTime, AzAttributeValueTime

createAzDataDayTimeDuration

AzDataDayTimeDuration createAzDataDayTimeDuration(boolean isNegativeDuration,
                                                  long days,
                                                  long hours,
                                                  long minutes,
                                                  long seconds,
                                                  int nanoSeconds)
Returns a helper data container for XACML #dayTimeDuration DataType


createAzDataYearMonthDuration

AzDataYearMonthDuration createAzDataYearMonthDuration(boolean isNegativeDuration,
                                                      long years,
                                                      long months)
Returns a helper data container for Xacml #yearMonthDuration


createAzDataByteArray

AzDataByteArray createAzDataByteArray(byte[] byteArray)
Returns a helper data container for boxed Java byte[] arrays