com.adobe.livecycle.rightsmanagement.client.infomodel
Interface Policy

All Superinterfaces:
java.lang.Cloneable

public interface Policy
extends java.lang.Cloneable

The Policy interface provides methods for creating and manipulating policies. Policy objects are implemented as XML documents according to the XML schema that the PDRL defines. Policies must have the following properties defined:

Policies can also have one or more of the following optional properties defined:

The changes made to Policy objects do not immediately affect the actual policies that they represent. To implement the changes, you must use PolicyManager to update the policies. To implement new Policy objects that you create, you use PolicyManager to register the policies.

The policy creator will often want to add a policy entry for the Publisher principal. Adding this principal provides permissions for the user that secures documents with this policy.

For information about creating new policies using the Document Security Java API, see the Creating a new policy using the Java API quick start in Programming with Adobe Experience Manager Forms.


Field Summary
static java.lang.String ENCRYPTION_TYPE_AES128
          Represents the AES encryption algorithm with a 128-bit key.
static java.lang.String ENCRYPTION_TYPE_AES256
          Represents the AES encryption algorithm with a 256-bit key.
static java.lang.String ENCRYPTION_TYPE_NONE
          Represents no encryption.
static java.lang.String ORGANIZATIONAL_POLICY
          Represents the Organizational policy type.
static java.lang.String USER_POLICY
          The constant that represents the User policy type.
 
Method Summary
 void addPolicyEntry(PolicyEntry policyEntry)
          Adds a policy entry that defines the set of permissions to the policy.
 void clearPolicyEntries()
          Removes all policy entries from the policy.
 void clearValidityPeriod()
          Removes the validity period from a policy.
 java.lang.String getAccessDeniedErrorMessage()
          Retrieves access denied error message defined in the policy.
 java.lang.String getAlternateId()
          Retrieves the alternate identification of the policy.
 java.util.Date getCreationTime()
          Retrieves the date that the policy was first registered with the Rights Management service.
 java.lang.String getDescription()
          Retrieves the description of the policy.
 java.lang.String getEncryptionAlgorithmAndKeySize()
          Retrieves encrpytion algorithm and key size defined in the policy.
 java.lang.String getId()
          Retrieves the identification value of the policy.
 int getInstanceVersion()
          Retrieves the instance version of the policy.
 java.util.Date getLastModifiedTime()
          Retrieves the date that the policy was last modified.
 java.lang.String getName()
          Retrieves the name of the policy.
 int getOfflineLeasePeriod()
          Retrieves the offline lease period.
 User getOwner()
          Retrieves the owner of the policy.
 java.util.List getPolicyEntries()
          Retrieves the policy entries for the policy.
 java.util.Map getPolicyProperties()
          Retrieves all the properties defined in the policy.
 java.lang.String getPolicySetName()
          Retrieves the name of the policy set that contains this policy.
 java.lang.String getSchemaVersion()
          Retrieves the version of the PDRL schema used to define the policy.
 java.lang.String getType()
          Retrieves the type of the policy.
 ValidityPeriod getValidityPeriod()
          Retrieves the validity period of the policy.
 java.lang.String getWatermarkId()
          Retrieves the identification of the watermark used with this policy.
 boolean isCertificateAuthenticationAllowed()
          Retrieves the boolean which specifies if certificate authentication is allowed for the policy.
 boolean isDeleted()
          Retrieves whether the policy is active or deleted.
 boolean isEncryptAttachmentsOnly()
          Retrieves whether only document attachments should be encrypted or both the document content and the attachment should be encrypted.
 boolean isExtendedUsageTrackingEnabled()
          Retrieves the boolean which specifies if extended usage tracking is allowed for the policy.
 boolean isKerberosAuthenticationAllowed()
          Retrieves the boolean which specifies if kerberos based authentication is allowed for the policy.
 boolean isOverrideAuthenticationSettings()
          Retrieves the authentication settings override flag for the policy.
 boolean isPlaintextMetadata()
          Retrieves whether the metadata of documents that are protected with this policy is encrypted.
 boolean isThirdPartyAuthenticationAllowed()
          Retrieves the boolean which specifies if third party authentication is allowed for the policy.
 boolean isTracked()
          Retrieves whether the Rights Management service logs events that involve this policy.
 boolean isUsernamePwdAuthenticationAllowed()
          Retrieves the boolean which specifies if username password authentication is allowed for the policy.
 void removePolicyEntry(PolicyEntry policyEntry)
          Removes a policy entry from the policy.
 void setAccessDeniedErrorMessage(java.lang.String accessDeniedErrorMessage)
          Set the new access denied error message for the policy.
 void setAlternateId(java.lang.String alternateId)
          Sets the unique alternate identification for the policy.
 void setCertificateAuthenticationAllowed(boolean certificateAuthenticationAllowed)
          Set the certificate flag for the policy.
 void setDescription(java.lang.String policyDescription)
          Sets the description of the policy.
 void setEncryptAttachmentsOnly(boolean encryptAttachmentsOnly)
          Specifies whether only document attachments should be encrypted or both the document content and the attachment should be encrypted.
 void setEncryptionAlgorithmAndKeySize(java.lang.String encrpytionAlgorithm)
          Set the new encrpytion algorithm and key size for the policy.
 void setExtendedUsageTrackingEnabled(boolean extendedUsageTrackingEnabled)
          Set the extended usage tracking flag for the policy.
 void setKerberosAuthenticationAllowed(boolean kerberosAuthenticationAllowed)
          Set the kerberos flag for the policy.
 void setName(java.lang.String name)
          Sets the name of the policy.
 void setOfflineLeasePeriod(int days)
          Sets the length of time after users synchronize with the Rights Management service that documents protected with this policy can be opened offline.
 void setOverrideAuthenticationSettings(boolean b)
          Sets the authentication settings override flag for the policy, Setting this to true, will enable all authentication types.
 void setPlaintextMetadata(boolean plaintextMetadata)
          Specifies whether document metadata is encrypted when the document is protected with this policy.
 void setPolicyProperties(java.util.Map newProps)
          Set the new properties for the policy.
 void setPolicySetName(java.lang.String policySetName)
          Sets the name of the policy set that contains this policy.
 void setThirdPartyAuthenticationAllowed(boolean thirdPartyAuthenticationAllowed)
          Set the third party authentication flag for the policy.
 void setTracked(boolean tracked)
          Specifies whether to log events regarding user actions on documents protected with this policy.
 void setUsernamePwdAuthenticationAllowed(boolean usernamePwdAuthenticationAllowed)
          Set the username password flag for the policy.
 void setValidityPeriod(ValidityPeriod validityPeriod)
          Sets the validity period of the policy.
 void setWatermarkId(java.lang.String id)
          Sets the watermark to use with the policy.
 byte[] toXml()
          Retrieves an XML representation of the policy.
 

Field Detail

USER_POLICY

static final java.lang.String USER_POLICY
The constant that represents the User policy type.

See Also:
Constant Field Values

ORGANIZATIONAL_POLICY

static final java.lang.String ORGANIZATIONAL_POLICY
Represents the Organizational policy type.

See Also:
Constant Field Values

ENCRYPTION_TYPE_AES256

static final java.lang.String ENCRYPTION_TYPE_AES256
Represents the AES encryption algorithm with a 256-bit key.

See Also:
Constant Field Values

ENCRYPTION_TYPE_AES128

static final java.lang.String ENCRYPTION_TYPE_AES128
Represents the AES encryption algorithm with a 128-bit key.

See Also:
Constant Field Values

ENCRYPTION_TYPE_NONE

static final java.lang.String ENCRYPTION_TYPE_NONE
Represents no encryption.

See Also:
Constant Field Values
Method Detail

setName

void setName(java.lang.String name)
             throws PDRLException
Sets the name of the policy. The name must be unique depending on the scope defined by the current user:

The current user is determined by the user name and password that was used to to log into the Rights Management service. To see this method used in a code example, see the Creating a new policy using the Java API quick start in Programming with Adobe Experience Manager Forms.

Parameters:
name - A java.lang.String that holds the name to set for the policy. The maximum length of the java.lang.String you can use is 50 characters or errors can occur.
Throws:
PDRLException - if the specified name is longer than 50 characters.

getName

java.lang.String getName()
Retrieves the name of the policy.

Returns:
A java.lang.String that holds the name of the policy.

setPolicySetName

void setPolicySetName(java.lang.String policySetName)
                      throws PDRLException
Sets the name of the policy set that contains this policy. To see this method used in a code example, see the Creating a new policy using the Java API quick start in Programming with Adobe Experience Manager Forms.

Parameters:
policySetName - A java.lang.String value that specifies the name of the policy set to used by this policy. The maximum length of the String value is 50 characters or errors occur.
Throws:
PDRLException - If the specified name is longer than 50 characters.

getPolicySetName

java.lang.String getPolicySetName()
Retrieves the name of the policy set that contains this policy.

Returns:
A java.lang.String that holds the name of the policy set that contains this policy.

setDescription

void setDescription(java.lang.String policyDescription)
                    throws PDRLException
Sets the description of the policy. You can use the description to describe the intended use of policy.

Parameters:
policyDescription - A java.lang.String that holds the description of the policy. The maximum length of the java.lang.String you can use is 250 characters.
Throws:
PDRLException - if the specified description is longer than 250 characters.

getDescription

java.lang.String getDescription()
Retrieves the description of the policy.

Returns:
A java.lang.String that holds the description of the policy and null if no description is set.

getType

java.lang.String getType()
Retrieves the type of the policy.

Returns:
A java.lang.String that holds the policy type, which can be either Policy.ORGANIZATIONAL_POLICY or Policy.USER_POLICY.
See Also:
Policy.ORGANIZATIONAL_POLICY, Policy.USER_POLICY

getValidityPeriod

ValidityPeriod getValidityPeriod()
Retrieves the validity period of the policy. When a policy is always valid (both the starting date and expiration date are null), this method returns null.

Returns:
A ValidityPeriod object that represents the validity period of the policy.

setValidityPeriod

void setValidityPeriod(ValidityPeriod validityPeriod)
                       throws PDRLException
Sets the validity period of the policy. The validity period defines the period of time during which the policy provides access to the documents it protects. The validity period can define the expiration date, the date when the policy becomes valid, or both. When a policy is not valid, the documents that the policy protects cannot be opened.

The validity period is an optional property. To see this method used in a code example, see the Creating a new policy using the Java API quick start in Programming with Adobe Experience Manager Forms.

Parameters:
validityPeriod - A ValidityPeriod object for the policy and null to specify no validity period.
Throws:
PDRLException - If an error occurred during this operation.

clearValidityPeriod

void clearValidityPeriod()
Removes the validity period from a policy. You can also use the setValidityPeriod(null) method to remove the validity period.

See Also:
PolicyEntry

getPolicyEntries

java.util.List getPolicyEntries()
Retrieves the policy entries for the policy.

Returns:
A java.util.List object that contains PolicyEntry objects that represent the policy entries associated with the policy.
See Also:
PolicyEntry

addPolicyEntry

void addPolicyEntry(PolicyEntry policyEntry)
                    throws PDRLException
Adds a policy entry that defines the set of permissions to the policy. To see this method used in a code example, see the Creating a new policy using the Java API quick start in Programming with Adobe Experience Manager Forms.

Parameters:
policyEntry - A PolicyEntry object to add to the policy.
Throws:
PDRLException - If an error occurs during this operation.
See Also:
PolicyEntry

removePolicyEntry

void removePolicyEntry(PolicyEntry policyEntry)
                       throws PDRLException
Removes a policy entry from the policy.

Parameters:
policyEntry - The PolicyEntry object that represents the policy entry to remove from the policy.
Throws:
PDRLException - If an error occurs during this operation.
See Also:
PolicyEntry

clearPolicyEntries

void clearPolicyEntries()
Removes all policy entries from the policy.

See Also:
PolicyEntry

isTracked

boolean isTracked()
Retrieves whether the Rights Management service logs events that involve this policy.

Returns:
true if events are logged and false if events are not logged.
See Also:
Policy.setTracked(boolean)

getOfflineLeasePeriod

int getOfflineLeasePeriod()
Retrieves the offline lease period.

Returns:
An integer that holds the length of the offline lease period for this policy, in days. Returns 0 if this policy does not permit access to the document while offline.

getWatermarkId

java.lang.String getWatermarkId()
Retrieves the identification of the watermark used with this policy.

Returns:
A java.lang.String that holds the unique identifier for the watermark and null if no watermark is used.

setTracked

void setTracked(boolean tracked)
Specifies whether to log events regarding user actions on documents protected with this policy. Examples of user actions are opening documents and printing documents.

Parameters:
tracked - The value true specifies that the user's actions are logged and false means that a user's actions are not logged. The default value is true.

setOfflineLeasePeriod

void setOfflineLeasePeriod(int days)
                           throws PDRLException
Sets the length of time after users synchronize with the Rights Management service that documents protected with this policy can be opened offline. Users can synchronize with the Rights Mangement service by using one of two methods:

The policy permissions must be configured to allow offline use of documents. To see this method used in a code example, see the Creating a new policy using the Java API quick start in Programming with Adobe Experience Manager Forms.

Parameters:
days - An integer value for the length of the offline lease (in days). days can be any value greater than zero and less than 10000, and null to use the default offline lease period. The default offline lease period is set using Adobe Experience Manager Forms administrator web pages.
Throws:
PDRLException - If an error occurs during this operation.

setWatermarkId

void setWatermarkId(java.lang.String id)
                    throws PDRLException
Sets the watermark to use with the policy.

Parameters:
id - A java.lang.String that contains the watermark identification or null if no watermark is used.
Throws:
PDRLException - If an error occurs during this operation.
See Also:
Watermark.getId()

isPlaintextMetadata

boolean isPlaintextMetadata()
Retrieves whether the metadata of documents that are protected with this policy is encrypted.

Returns:
true if metadata is not encrypted and false if the metadata is encyrpted.
See Also:
Policy.setPlaintextMetadata(boolean)

isEncryptAttachmentsOnly

boolean isEncryptAttachmentsOnly()
Retrieves whether only document attachments should be encrypted or both the document content and the attachment should be encrypted.

Returns:
true if only attachments are encrypted and false if both the document content and the attachments are encrypted.
See Also:
Policy.setEncryptAttachmentsOnly(boolean)

setPlaintextMetadata

void setPlaintextMetadata(boolean plaintextMetadata)
                          throws PDRLException
Specifies whether document metadata is encrypted when the document is protected with this policy. Search engines use document metadata for matching documents with keywords. If the metadata is encrypted, then search engines cannot use it. If the policy contains NoEncryption for the encryption setting, then this method does not perform an action.

setPlaintextMetadata can be set only when a policy is initially registered with the Rights Management service. You cannot change this setting for policies that are already registered.

Parameters:
plaintextMetadata - true if document metadata should not be encrypted and false if metadata should be encrypted. plaintextMetadata is false by default.

plaintextMetadata must be false if the policy is set to encrypt only document attachments.

Throws:
PDRLException - if plaintextMetadata is true and the policy is set to encrypt only document attachments.
See Also:
setEncryptAttachmentsOnly

setEncryptAttachmentsOnly

void setEncryptAttachmentsOnly(boolean encryptAttachmentsOnly)
                               throws PDRLException
Specifies whether only document attachments should be encrypted or both the document content and the attachment should be encrypted. If only the attachment is encrypted, then the policy protects only document attachments, not the document. By default, both the document and the attachments are encrypted. If the policy contains NoEncryption for the encryption setting, then this method does not perform an action.

setEncryptedAttachmentsOnly can be set only when a policy is initially registered with the Rights Mangement service. You cannot change this setting for policies that are already registered.

Parameters:
encryptAttachmentsOnly - true to specify that only the attachment should be encrypted and false if both the document and the attachment should be encrypted. The default value is false.

If encryptAttachmentsOnly is true, then the policy must be set to encrypt document metadata.

Throws:
PDRLException - if encryptAttachmentsOnly is true and the policy is not set to encrypt document metadata.

getCreationTime

java.util.Date getCreationTime()
Retrieves the date that the policy was first registered with the Rights Management service. The date is set according to the date on the server.

Returns:
A java.util.Date object that contains the date the policy was created.

getLastModifiedTime

java.util.Date getLastModifiedTime()
Retrieves the date that the policy was last modified. The date is set according to the date on the server.

Returns:
A java.util.Date object that contains the date the policy was last modified.

getId

java.lang.String getId()
Retrieves the identification value of the policy.

Returns:
A java.lang.String that specifies the identification value of the policy and null if this Policy object represents a policy not yet registered with the Rights Management service.

getSchemaVersion

java.lang.String getSchemaVersion()
Retrieves the version of the PDRL schema used to define the policy.

Returns:
A java.lang.String that holds the version of the PDRL schema.

toXml

byte[] toXml()
             throws PDRLException
Retrieves an XML representation of the policy. The structure of the XML is defined by the PDRL schema.

Returns:
An array of bytes that contains an XML document that represents the policy.
Throws:
PDRLException
See Also:
InfomodelObjectFactory.createPolicy()

getInstanceVersion

int getInstanceVersion()
Retrieves the instance version of the policy. The instance version tracks the number of times a registered policy is modified. The instance version is set to 1 when a policy is first registered with the Rights Management service. The instance version increments by 1 each time the policy is modified.

Returns:
An integer that holds the instance version of the policy.

isDeleted

boolean isDeleted()
Retrieves whether the policy is active or deleted. Active policies can currently be used to protect documents. Deleted policies can no longer be used to protect documents but can still ensure confidentiality for documents that it protected prior to being deleted.

Returns:
true if the policy is deleted and false if the policy is active.
See Also:
deletePolicy

getAlternateId

java.lang.String getAlternateId()
Retrieves the alternate identification of the policy.

Returns:
A java.lang.String that holds the alternate identification of the policy and null if no alternate identification was set.
See Also:
Policy.setAlternateId(String)

setAlternateId

void setAlternateId(java.lang.String alternateId)
                    throws PDRLException
Sets the unique alternate identification for the policy. The alternate identification is useful if you want to cross-reference policies by using the identification scheme of an integrated third-party application.

Parameters:
alternateId - A java.lang.String that holds the alternate identification of the policy. The maximum length of the java.lang.String you can use is 255 characters.

No two policies can use the same alternate identification.

Throws:
PDRLException - if alternateId is longer than 255 characters.

getOwner

User getOwner()
Retrieves the owner of the policy. The owner of the policy is the user who registered the policy with the Rights Management service.

Returns:
null if a policy is contained in a policy set, and returns a valid User object if the policy is contained in My Policies.
See Also:
PolicyManager

getPolicyProperties

java.util.Map getPolicyProperties()
Retrieves all the properties defined in the policy. The properties are returned in a map as a set of name/value pairs. The values will be either single String or arrays of Strings if the property was multi-valued.

Returns:
A java.util.Map of name/value pairs.

setPolicyProperties

void setPolicyProperties(java.util.Map newProps)
Set the new properties for the policy.

Parameters:
newProps - Each value in the java.util.Map must be either a string or an array of strings.

getEncryptionAlgorithmAndKeySize

java.lang.String getEncryptionAlgorithmAndKeySize()
Retrieves encrpytion algorithm and key size defined in the policy.

Returns:
A java.lang.String.

setEncryptionAlgorithmAndKeySize

void setEncryptionAlgorithmAndKeySize(java.lang.String encrpytionAlgorithm)
                                      throws PDRLException
Set the new encrpytion algorithm and key size for the policy.

Parameters:
encrpytionAlgorithm - A string contains the new encrpytion algorithm and key size.
Throws:
PDRLException

getAccessDeniedErrorMessage

java.lang.String getAccessDeniedErrorMessage()
Retrieves access denied error message defined in the policy.

Returns:
A java.lang.String.

setAccessDeniedErrorMessage

void setAccessDeniedErrorMessage(java.lang.String accessDeniedErrorMessage)
Set the new access denied error message for the policy.

Parameters:
accessDeniedErrorMessage - A string contains the new access denied error message.

setOverrideAuthenticationSettings

void setOverrideAuthenticationSettings(boolean b)
Sets the authentication settings override flag for the policy, Setting this to true, will enable all authentication types. User needs to explicitly disable unwanted authentication types by using the respective setters.

Parameters:
b - boolean which specifies if we want to override the authentication settings in the policy

isOverrideAuthenticationSettings

boolean isOverrideAuthenticationSettings()
Retrieves the authentication settings override flag for the policy.

Returns:
A boolean.

isThirdPartyAuthenticationAllowed

boolean isThirdPartyAuthenticationAllowed()
Retrieves the boolean which specifies if third party authentication is allowed for the policy.

Returns:
A boolean.

setThirdPartyAuthenticationAllowed

void setThirdPartyAuthenticationAllowed(boolean thirdPartyAuthenticationAllowed)
Set the third party authentication flag for the policy.

Parameters:
thirdPartyAuthenticationAllowed - boolean which specifies if we want to allow third party authentication for the policy

isKerberosAuthenticationAllowed

boolean isKerberosAuthenticationAllowed()
Retrieves the boolean which specifies if kerberos based authentication is allowed for the policy.

Returns:
A boolean.

setKerberosAuthenticationAllowed

void setKerberosAuthenticationAllowed(boolean kerberosAuthenticationAllowed)
Set the kerberos flag for the policy.

Parameters:
kerberosAuthenticationAllowed - boolean which specifies if we want to allow kerberos based authentication for the policy

isCertificateAuthenticationAllowed

boolean isCertificateAuthenticationAllowed()
Retrieves the boolean which specifies if certificate authentication is allowed for the policy.

Returns:
A boolean.

setCertificateAuthenticationAllowed

void setCertificateAuthenticationAllowed(boolean certificateAuthenticationAllowed)
Set the certificate flag for the policy.

Parameters:
certificateAuthenticationAllowed - boolean which specifies if we want to allow certificate authentication for the policy

isUsernamePwdAuthenticationAllowed

boolean isUsernamePwdAuthenticationAllowed()
Retrieves the boolean which specifies if username password authentication is allowed for the policy.

Returns:
A boolean.

setUsernamePwdAuthenticationAllowed

void setUsernamePwdAuthenticationAllowed(boolean usernamePwdAuthenticationAllowed)
Set the username password flag for the policy.

Parameters:
usernamePwdAuthenticationAllowed - boolean which specifies if we want to allow username password authentication for the policy

isExtendedUsageTrackingEnabled

boolean isExtendedUsageTrackingEnabled()
Retrieves the boolean which specifies if extended usage tracking is allowed for the policy.

Returns:
A boolean.

setExtendedUsageTrackingEnabled

void setExtendedUsageTrackingEnabled(boolean extendedUsageTrackingEnabled)
Set the extended usage tracking flag for the policy.

Parameters:
extendedUsageTrackingEnabled - boolean which specifies if we want to allow extended usage tracking for the policy