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:

• One or more policy entries
• A name that uniquely identifies the policy

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

• A description
• A validity period
• A watermark
• A tracked flag
• An offline lease period
• An encrypt attachments only flag
• An plaintext metadata flag
• An alternate identification for the policy

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:

• If the current user is an end user, the name must be unique to all organizational policies and the user policies that the user owns.
• If the current user is an administator, the name must be unique to all organizational policies.

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:

• Open a policy-protected document.
• Use Acrobat or Adobe Reader to explicitly synchronize.

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