com.adobe.flashaccess.sdk.protocol.license
Class LicenseRequestMessage

java.lang.Object
  extended by com.adobe.flashaccess.sdk.protocol.AbstractRequestMessage
      extended by com.adobe.flashaccess.sdk.protocol.RequestMessageBase
          extended by com.adobe.flashaccess.sdk.protocol.license.LicenseRequestMessage

public class LicenseRequestMessage
extends RequestMessageBase

License request. To process a license request, call getContentInfo() for information about the content being accessed and the policies applied to the content at packaging time.

If the user is allowed to access the content, issue a license. If there are multiple policies, or if the server has an updated version of the desired policy, call setSelectedPolicy() to indicate the policy to use. If the policy supports root licenses, the server may decide to issue a leaf license, a root license, or both. The server can decide which type of license to issue by calling getExistingLicenseInfo() (for example, if the user has already been issued a leaf license for this policy, the server can just send a root license). When issuing a leaf license (when not in preview mode), ContentInfo.setKeyRetrievalInfo() method must be called to specify information required to decrypt the key in the metadata. To generate the license call generateLicense(). The license may be modified after it is generated.

If the user is not authorized to view the content, call setErrorData() and provide the error information.

If the client supports the optional preview license phase, the server issues preview licenses so the client can see what rights they will be granted. The preview license does not contain the key for decrypting content. License preview can be used to determine if a user will be able to play the content before making a purchase.


Nested Class Summary
static class LicenseRequestMessage.RequestPhase
          Indicates the phase for the license request.
 
Field Summary
 
Fields inherited from class com.adobe.flashaccess.sdk.protocol.RequestMessageBase
SERVER_CONFIG_NOT_PRESENT
 
Method Summary
 boolean clientHasLeafForPolicy(java.lang.String policyId)
          Based on the license info sent in the request, this method determines if the client has a leaf license for the specified policy.
 boolean clientHasRootForPolicy(java.lang.String policyId)
          Based on the license info sent in the request, this method determines whether the client has a root license for the specified policy.
 License generateLicense(License.LicenseType licenseType)
          Generates a license of the specified type for the policy indicated by LicenseRequestMessage.getSelectedPolicy().
 java.util.Collection getAdditionalRecipients()
          Retrieves a list of additional machine certificates to bind the license to, in addition to the machine token specified in the request.
 ContentInfo getContentInfo()
          Retrieves information about the content for which a license is requested.
 java.util.Collection getExistingLicenseInfo()
          Retrieves a list of licenses present on the client for this content.
 java.util.Collection getLicenses()
          Retrieves the licenses which were generated by LicenseRequestMessage.generateLicense(com.adobe.flashaccess.sdk.license.License.LicenseType) for this request.
 LicenseRequestMessage.RequestPhase getRequestPhase()
          Indicates whether the client sent a preview or acquire license request.
 Policy getSelectedPolicy()
          Retrieves the policy which will be used to generate the license.
 void setAdditionalRecipients(java.util.Collection machineCerts)
          Specify additional machine certificates to bind the license to.
 void setSelectedPolicy(Policy policy)
          Sets the policy to use to generate the license.
 
Methods inherited from class com.adobe.flashaccess.sdk.protocol.RequestMessageBase
getAuthenticationToken, getClientState, getMachineToken, getRawAuthenticationToken, getServerConfigVersion
 
Methods inherited from class com.adobe.flashaccess.sdk.protocol.AbstractRequestMessage
getClientLocale, getErrorData, getMessageId, setErrorData
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

getRequestPhase

public LicenseRequestMessage.RequestPhase getRequestPhase()
Indicates whether the client sent a preview or acquire license request. The response to a preview request is identical to that of acquire, except the license will not contain the key for decrypting content.

Returns:
The license request phase.

getContentInfo

public ContentInfo getContentInfo()
Retrieves information about the content for which a license is requested.

Returns:
Information about the content for which a license is requested.

getExistingLicenseInfo

public java.util.Collection getExistingLicenseInfo()
Retrieves a list of licenses present on the client for this content. The server may examine this information to determine if a root or leaf license should be issued to the user.

Returns:
Collection<ClientLicenseInfo> containing information about licenses on the client, or an empty list if no license information was sent.

setAdditionalRecipients

public void setAdditionalRecipients(java.util.Collection machineCerts)
Specify additional machine certificates to bind the license to. By default, the license will be bound to the machine token specified in the request. Use this to specify additional machines (the certificate for the machine token in the request does not need to be included in this list). If additional recipients are specified in the license, the license may be transferred among those machines without contacting the license server. Any invalid certificates (for example, expired, revoked, or the wrong certificate type) will be ignored. This method does not check the revocation list specified in the HandlerConfiguration; the caller should ensure the certificates do not appear on the revocation list before calling this method.

Parameters:
machineCerts - Collection<X509Certificate> specifying additional machine certificates to bind the license to.

getAdditionalRecipients

public java.util.Collection getAdditionalRecipients()
Retrieves a list of additional machine certificates to bind the license to, in addition to the machine token specified in the request. If additional recipients are specified in the license, the license may be transferred among those machines without contacting the license server.

Returns:
Collection<X509Certificate> specifying additional machine certificates to bind the license to, or an empty list if the license will only be bound to the machine in the request.

clientHasRootForPolicy

public boolean clientHasRootForPolicy(java.lang.String policyId)
Based on the license info sent in the request, this method determines whether the client has a root license for the specified policy.

Parameters:
policyId - The policy identifier.
Returns:
true if the client indicated it has a root license for the policy, false otherwise.

clientHasLeafForPolicy

public boolean clientHasLeafForPolicy(java.lang.String policyId)
Based on the license info sent in the request, this method determines if the client has a leaf license for the specified policy.

Parameters:
policyId - The policy identifier.
Returns:
true if the client indicated it has a leaf license for the policy, false otherwise.

setSelectedPolicy

public void setSelectedPolicy(Policy policy)
Sets the policy to use to generate the license. The server may wish to specify a policy if the content contains multiple policies or if the server has an updated version of the desired policy which was not included in a policy update list. If policy update lists are being used, the policy specified here should be selected from ContentInfo.getUpdatedPolicies().

If this method is called after LicenseRequestMessage.generateLicense(com.adobe.flashaccess.sdk.license.License.LicenseType), any licenses previously generated under a different policy will be deleted; those licenses will not be sent to the client and will not be included in the list of licenses returned by LicenseRequestMessage.getLicenses().

Parameters:
policy - The policy to use to generate the license; it must not be null.

getSelectedPolicy

public Policy getSelectedPolicy()
Retrieves the policy which will be used to generate the license.

By default, the first valid policy in the content metadata will be used (a policy is considered to be valid if it has not been revoked according to the policy update list). If a policy update list was specified, the update list will be consulted before selecting a valid policy. The policy expiration date and other restrictions are not considered when selecting the default policy.

To override the default, call LicenseRequestMessage.setSelectedPolicy(Policy).

Returns:
The selected policy, or null if no valid policy was found.

generateLicense

public License generateLicense(License.LicenseType licenseType)
                        throws PolicyEvaluationException,
                               LicenseGenerationException
Generates a license of the specified type for the policy indicated by LicenseRequestMessage.getSelectedPolicy().

If the selected policy has a root license and the request is not a Preview request (getRootLicenseId() != null), the server must decide whether to issue a leaf or root license to the client. The client must have the leaf license in order to decrypt the content. If the leaf license for the content expires, a root license can be issued to extend the expiration date for this piece of content and any other content which shares the same policy (and therefore shares the root license). To determine whether a root or leaf license should be sent, the server should examine the licenses which the client currently has for this content. The server can either search the list of existing licenses (getContentInfo().getExistingLicenseInfo()) or call LicenseRequestMessage.clientHasLeafForPolicy(String) to determine if the client has a leaf license for the specified policy identifier. If the client does not have a leaf license for the desired policy, a leaf license must be issued to the client in order to be able to view the content. If a leaf license is already present, a root license may be issued. Only a leaf license may be issued in response to a preview request.

When generating a license, the policy is evaluated as follows:

If any of the above policy checks fails, a PolicyEvaluationException is thrown. Upon receiving this exception, the server should either try a different policy or call setErrorData() with the error specified in PolicyEvaluationException.getErrorData(). If the server does not take either action, the error AdobeErrorData.LACQ_USER_NOT_AUTHORIZED will be returned to the client.

Changes may be made to the license before the final response is sent to the user. For example:

If authentication is required, the server is responsible for ensuring that the user specified in the license is authorized to view the content (the user name in the license is obtained from the authentication token). The response is sent when the handler's close() method is called. If getErrorData() is not null, an error will be returned to the client and the generated licenses for this LicenseRequestMessage will not be sent.

Both a root and a leaf license may be issued to the client by calling this method once for each license type. Only one of each license type may be issued for a single request.

Parameters:
licenseType - The type of license to generate.
Returns:
The license
Throws:
PolicyEvaluationException - if the conditions required in the policy have not been met.
LicenseGenerationException - if information required to generate the license was not provided. This can occur if getSelectedPolicy() returns null or if the LicenseType is LicenseType.Leaf and the RequestPhase is RequestPhase.Acquire, but no KeyRetrievalInfo was specified in ContentInfo.

getLicenses

public java.util.Collection getLicenses()
Retrieves the licenses which were generated by LicenseRequestMessage.generateLicense(com.adobe.flashaccess.sdk.license.License.LicenseType) for this request. There may be more than one if both a root and leaf license was generated.

Returns:
Collection<License> containing the licenses generated for this request, or an empty list if no licenses were generated or getErrorData() does not return null.


[an error occurred while processing this directive] [an error occurred while processing this directive]