com.adobe.flashaccess.sdk.policy
Class Policy

java.lang.Object
  com.adobe.flashaccess.sdk.policy.Policy

public class Policy
extends java.lang.Object

This class contains information for a license server to digest before issuing a license.

Policy information is baked into a protected content's header at the time of packaging. During license acquisition, the information in the policy tells the client whether it needs to authenticate and may also contain custom data to be interpreted by the client application. The embedded policy information is also sent to the license server in the license request. The rights specified in the policy indicate the rights that the license will contain (although the license server may modify the rights in the license, if desired).

The parameters contained within this class are:

• The policy identifier (automatically generated when a policy is created)
• The revision number (automatically updated when policy is modified)
• The rights (required)
• The policy expiration settings (optional)
• The license caching settings (for example, the license caching period) (optional)
• The policy name (optional)
• The root license identifier (optional, automatically generated when a policy is created)
• The license server information (required)
• Custom properties (optional)

The following is an example of how to create a serialized policy that allows the Play right.

                Policy pol = new Policy(false); // No root license ID 


                
                LicenseServerInfo lInfo = new LicenseServerInfo(authRequired, authentication_info);

                pol.setLicenseServerInfo(lInfo);


                
                pol.setName("Policy_001");


                
                // Rights

                PlayRight pr = new PlayRight();

                List<Right> rightsList = new ArrayList<Right>();

                rightsList.add(pr);

                pol.setRights(rightsList);


        
                // Custom Properties

                ApplicationProperties customProps = new ApplicationProperties();

                customProps.addUTF8String("customDataName_01", "New customer-specified information");

                customProps.addUTF8String("customDataName_02", "Other useful information to include");

                pol.setCustomProperties(customProps);


                
                // Marshal policy

                byte[] bytes = pol.getBytes();


                
                // Unmarshal policy

                Policy newPolicy = new Policy( bytes );

  

Field Summary

static long	LICENSE_CACHING_DISABLED License caching is not allowed.
static long	LICENSE_CACHING_UNLIMITED Unlimited license caching.
static long	MAX_LICENSE_CACHING_DURATION The maximum license caching period, in seconds.
static long	MAX_RELATIVE_DURATION The maximum policy relative duration, in seconds.
static long	RELATIVE_DURATION_UNLIMITED No relative policy expiration date exists.

Constructor Summary

Policy(boolean hasRootLicense)
Creates a new Policy and automatically generates a new policy identifier.

Policy(byte[] policy)
This constructor parses an existing policy from the given byte array.

Method Summary

void	checkValidity() Determines if this Policy is valid (for example, all required fields are specified and no parameters conflict).
byte[]	getBytes() Retrieves an encoded byte array representation of the policy.
ApplicationProperties	getCustomProperties() Retrieves the optional customer-defined properties to include in the policy.
java.lang.String	getId() Retrieves the identifier generated for the policy.
long	getLicenseCachingDuration() Retrieves the duration (in seconds) during which a license can be cached by the client.
java.util.Date	getLicenseCachingEndDate() Retrieves the date after which a license may not be cached by the client.
LicenseServerInfo	getLicenseServerInfo() Retrieves the information that the client needs when attempting license acquisition.
java.lang.String	getName() Retrieves the friendly name for the policy (optional).
java.util.Date	getPolicyEndDate() Retrieves the date after which content protected with the policy is not valid.
long	getPolicyRelativeDuration() Retrieves the optional duration (in seconds) during which content protected with the policy is valid, starting from the time it was packaged.
java.util.Date	getPolicyStartDate() Retrieves the date from which content protected with the policy is valid.
int	getRevision() Retrieves the revision number of this Policy.
java.util.Collection	getRights() Retrieves the rights associated with the policy.
java.lang.String	getRootLicenseId() Retrieves the root license identifier associated with this Policy.
boolean	hasAbsoluteExpiration() Indicates whether the absolute end date has been set.
boolean	hasRelativeExpiration() Indicates whether the relative policy duration was set.
void	setCustomProperties(ApplicationProperties customProperties) Sets the optional customer-defined properties to include in the policy.
void	setLicenseCachingDuration(long seconds) Sets the number of seconds the license may be cached by the client, starting from the time the client downloads the license.
void	setLicenseCachingEndDate(java.util.Date endDate) Sets the date after which a license may not be cached by the client.
void	setLicenseServerInfo(LicenseServerInfo licenseServerInfo) Sets the information that the client needs when attempting license acquisition.
void	setName(java.lang.String policyName) Sets the friendly name for the policy (optional).
void	setPolicyEndDate(java.util.Date endDate) Sets the date after which content protected with the policy is not valid.
void	setPolicyRelativeDuration(long seconds) Sets the relative policy duration, which is the duration (in seconds) the content protected with this Policy is valid (optional).
void	setPolicyStartDate(java.util.Date startDate) Sets the date from which content protected with the policy is valid.
void	setRights(java.util.Collection rights) Sets the rights allowed by this policy.
boolean	wasModified() Indicates whether the policy has changed since the Policy object was created.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

MAX_RELATIVE_DURATION

public static final long MAX_RELATIVE_DURATION

The maximum policy relative duration, in seconds.

RELATIVE_DURATION_UNLIMITED

public static final long RELATIVE_DURATION_UNLIMITED

No relative policy expiration date exists.

MAX_LICENSE_CACHING_DURATION

public static final long MAX_LICENSE_CACHING_DURATION

The maximum license caching period, in seconds.

LICENSE_CACHING_DISABLED

public static final long LICENSE_CACHING_DISABLED

License caching is not allowed.

LICENSE_CACHING_UNLIMITED

public static final long LICENSE_CACHING_UNLIMITED

Unlimited license caching.

Constructor Detail

Policy

public Policy(boolean hasRootLicense)

Creates a new Policy and automatically generates a new policy identifier. If hasRootLicense is true, this constructor also generates a root license identifier (there is a one-to-one mapping between a root license and a policy). The revision number is 0 until Policy.getBytes() is called.

Parameters:

hasRootLicense - true the policy has a root license, false otherwise.

Policy

public Policy(byte[] policy)
       throws PolicyException,
              EncodingException

This constructor parses an existing policy from the given byte array.

Parameters:

policy - The policy from which to construct this Policy.

Throws:

EncodingException - Unable to parse the byte array into a Policy.

PolicyException - The Policy is missing required fields or contains conflicting entries.

Method Detail

getBytes

public byte[] getBytes()
                throws PolicyException,
                       EncodingException

Retrieves an encoded byte array representation of the policy.

If this Policy was created from an empty constructor, the revision number will be 1. If this was an existing policy and changes were made to the policy, the revision number will be incremented by one. Otherwise, the revision number will not change.

The validity of the policy is first checked before encoding into a byte array. Encoding will fail if Policy.checkValidity() throws an exception.

Returns:

A serialized representation of the policy.

Throws:

PolicyException - The Policy is missing required fields or contains conflicting entries.

EncodingException - Unable to encode the Policy to a byte array.

getRevision

public int getRevision()

Retrieves the revision number of this Policy. The revision number is incremented by Policy.getBytes(), but only when the policy has been modified. If two policies have the same revision number and Policy.wasModified() returns false, the policies are equal.

Returns:

the revision number of this Policy

wasModified

public boolean wasModified()

Indicates whether the policy has changed since the Policy object was created. If a policy is created using the Policy.Policy(byte[]) constructor, Policy.wasModified() will return false unless some attributes of the policy have been changed. Policy.wasModified() will always return true immediately after Policy.getBytes() has been called successfully. If two policies have the same revision number and Policy.wasModified() returns false, the policies are equal.

Returns:

true if the policy has been modified since it was last serialized, false otherwise.

getId

public java.lang.String getId()

Retrieves the identifier generated for the policy. The identifier does not change when the policy is updated.

Returns:

The identifier generated for the policy.

getName

public java.lang.String getName()

Retrieves the friendly name for the policy (optional). The name does not hold any meaning for Flash Access; it is simply a way to help users managing policies and packaging content to identify policies.

Returns:

The friendly name for the policy, or null if no name was provided.

setName

public void setName(java.lang.String policyName)

Sets the friendly name for the policy (optional).

Parameters:

policyName - The friendly name for the policy.

getRootLicenseId

public java.lang.String getRootLicenseId()

Retrieves the root license identifier associated with this Policy. The root license identifier is generated when the policy is created, and cannot be changed.

Returns:

The root license identifier associated with this Policy, or null if there is no root license.

getCustomProperties

public ApplicationProperties getCustomProperties()

Retrieves the optional customer-defined properties to include in the policy.

Returns:

The customer-defined properties to include in the policy.

setCustomProperties

public void setCustomProperties(ApplicationProperties customProperties)

Sets the optional customer-defined properties to include in the policy. These properties may be used by the client application before acquiring a license or by the server when issuing a license.

Parameters:

customProperties - The customer-defined properties to include in the policy.

getLicenseServerInfo

public LicenseServerInfo getLicenseServerInfo()

Retrieves the information that the client needs when attempting license acquisition.

Returns:

The information that the client needs when attempting license acquisition.

setLicenseServerInfo

public void setLicenseServerInfo(LicenseServerInfo licenseServerInfo)

Sets the information that the client needs when attempting license acquisition.

This information may only be set the first time the policy is created (it cannot be updated).

Parameters:

licenseServerInfo - The information that the client needs when attempting license acquisition.

getPolicyStartDate

public java.util.Date getPolicyStartDate()

Retrieves the date from which content protected with the policy is valid. Content cannot be viewed before this date.

When the policy is serialized and deserialized, dates are stored with second-precision (milliseconds are lost).

Returns:

The date from which content protected with the policy is valid, or null if the content is valid immediately.

setPolicyStartDate

public void setPolicyStartDate(java.util.Date startDate)

Sets the date from which content protected with the policy is valid. Content cannot be viewed before this date.

All dates must be between January 1, 1970 and December 31, 9999 (GMT)

If the end date has been set, it must be after the start date.

When the policy is serialized and deserialized, dates are stored with second-precision (milliseconds are lost).

Parameters:

startDate - The date from which content protected with the policy is valid, or null if the content is valid immediately.

getPolicyEndDate

public java.util.Date getPolicyEndDate()

Retrieves the date after which content protected with the policy is not valid. If set, content cannot be viewed after this date.

When the policy is serialized and deserialized, dates are stored with second-precision (milliseconds are lost).

The policy expiration also controls the deletion of client state associated with a license. For example, to enforce the Playback Window restriction, the client stores the time the user first plays the content. This information is deleted when the policy expires. Therefore, if the user obtains a new license, the playback window would start again.

Returns:

The date after which content protected with the policy is not valid, or null if there is no policy expiration date.

setPolicyEndDate

public void setPolicyEndDate(java.util.Date endDate)

Sets the date after which content protected with the policy is not valid. If set, content cannot be viewed after this date.

All dates must be between January 1, 1970 and December 31, 9999 (GMT)

Either the end date or relative duration may be set, but not both (setting the end date will remove the relative policy duration). If the start date has been set, it must be before the end date.

When the policy is serialized and deserialized, dates are stored with second-precision (milliseconds are lost).

The policy expiration also controls the deletion of client state associated with a license. For example, to enforce the Playback Window restriction, the client stores the time the user first plays the content. This information is deleted when the policy expires. Therefore, if the user obtains a new license, the playback window would start again.

Parameters:

endDate - The date after which content protected with the policy is not valid, or null if there is no policy expiration date.

getPolicyRelativeDuration

public long getPolicyRelativeDuration()

Retrieves the optional duration (in seconds) during which content protected with the policy is valid, starting from the time it was packaged.

The policy expiration also controls the deletion of client state associated with a license. For example, to enforce the Playback Window restriction, the client stores the time the user first plays the content. This information is deleted when the policy expires. Therefore, if the user obtains a new license, the playback window would start again.

Returns:

The policy's relative expiration, or Policy.RELATIVE_DURATION_UNLIMITED if no relative expiration is set.

setPolicyRelativeDuration

public void setPolicyRelativeDuration(long seconds)

Sets the relative policy duration, which is the duration (in seconds) the content protected with this Policy is valid (optional). When the relative policy duration is set, the validity period for each piece of content begins at the moment it is packaged.

Either the end date or relative duration may be set, but not both. Setting the relative policy expiration will remove the policy end date, if it is set.

The policy expiration also controls the deletion of client state associated with a license. For example, to enforce the Playback Window restriction, the client stores the time the user first plays the content. This information is deleted when the policy expires. Therefore, if the user obtains a new license, the playback window would start again.

Parameters:

seconds - The policy's relative expiration, or Policy.RELATIVE_DURATION_UNLIMITED if there is no relative expiration.

hasAbsoluteExpiration

public boolean hasAbsoluteExpiration()

Indicates whether the absolute end date has been set. By default, there is no expiration. A policy may have a relative or absolute expiration (or neither), but not both.

Returns:

true if the policy has an absolute expiration, false otherwise.

hasRelativeExpiration

public boolean hasRelativeExpiration()

Indicates whether the relative policy duration was set. By default, there is no expiration. A policy may have a relative or absolute expiration (or neither), but not both.

Returns:

true if the policy has a relative expiration, false otherwise.

getLicenseCachingDuration

public long getLicenseCachingDuration()

Retrieves the duration (in seconds) during which a license can be cached by the client. By default, the license may be cached indefinitely.

Returns:

The license caching period in seconds.

See Also:

Policy.LICENSE_CACHING_DISABLED, Policy.LICENSE_CACHING_UNLIMITED

setLicenseCachingDuration

public void setLicenseCachingDuration(long seconds)

Sets the number of seconds the license may be cached by the client, starting from the time the client downloads the license. As long as the license is cached and is valid, the client will not connect to the server to request a license.

To limit the cache time, set the value greater than 0. The value Policy.LICENSE_CACHING_DISABLED indicates licenses should not be cached. The value Policy.LICENSE_CACHING_UNLIMITED indicates licenses should be cached as long as the policy is valid.

Parameters:

seconds - The license caching period in seconds.

getLicenseCachingEndDate

public java.util.Date getLicenseCachingEndDate()

Retrieves the date after which a license may not be cached by the client. If set, a license cannot be cached after this date, but a user may still be able to download a license from the server each time they view the content.

When the policy is serialized and deserialized, dates are stored with second-precision (milliseconds are lost).

Returns:

The date after which a license may not be cached by the client, or null if there is no license caching end date (an license caching duration may still be specified to control caching behavior when the end date is null).

setLicenseCachingEndDate

public void setLicenseCachingEndDate(java.util.Date endDate)

Sets the date after which a license may not be cached by the client. As long as the license is cached and is valid, the client will not connect to the server to request a license.

Alternatively, a relative cache duration may be set using Policy.setLicenseCachingDuration(long). If the license caching end date is set to a non-null value, this takes precedence over the license caching duration.

All dates must be between January 1, 1970 and December 31, 9999 (GMT)

When the policy is serialized and deserialized, dates are stored with second-precision (milliseconds are lost).

Parameters:

endDate - The date after which licenses may not be cached.

getRights

public java.util.Collection getRights()

Retrieves the rights associated with the policy. The rights in the policy indicate the rights that the license will contain (although the license server may modify the rights in the license if desired). At least one right must be present in the policy.

Returns:

Collection<Right>, or an empty list if no rights have been set.

setRights

public void setRights(java.util.Collection rights)

Sets the rights allowed by this policy. The rights in the policy indicate the rights that the license will contain (although the license server may modify the rights in the license if desired).

Parameters:

rights - Collection<Right> containing containing rights to grant.

checkValidity

public void checkValidity()
                   throws PolicyException

Determines if this Policy is valid (for example, all required fields are specified and no parameters conflict).

Required fields:

• The rights
• License server parameters

Throws:

PolicyException - if there is a problem with the policy.