com.intertrust.wasabi.drm

Class Engine

java.lang.Object

com.intertrust.wasabi.drm.Engine

public final class Engine
extends java.lang.Object

The Engine is the entry point to get information about the current state of the DRM on the device and to ask the DRM layer to perform some actions such as processing a service token, updating the security data or vacuuming the persistent database in order to remove expired objects.

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	BUILD_DATE_PROPERTY build date property.
static java.lang.String	CACHE_POLICY_PROPERTY tells how links are cached.
static java.lang.String	HTTP_CONNECTION_TIMEOUT_PROPERTY type is Integer
static java.lang.String	HTTP_IO_TIMEOUT_PROPERTY type is Integer
static java.lang.String	HTTP_PROXY_ENABLED_PROPERTY type is Boolean
static java.lang.String	HTTP_PROXY_HOST_NAME_PROPERTY type is String
static java.lang.String	HTTP_PROXY_PORT_PROPERTY type is Integer
static java.lang.String	HTTP_PROXY_SYSTEM_DEFAULT_PROPERTY type is Boolean
static java.lang.String	HTTPS_PROXY_HOST_NAME_PROPERTY type is String
static java.lang.String	HTTPS_PROXY_PORT_PROPERTY type is Integer
static java.lang.String	IS_PERSONALIZED_PROPERTY type is Boolean
static java.lang.String	NEMO_PROPERTY type is com.intertrust.wasabi.Attribute
static java.lang.String	PERSONALITY_PROPERTY type is com.intertrust.wasabi.Attribute
static java.lang.Integer	POLICY_DO_NOT_RELOAD_LINKS value for the CACHE_POLICY_PROPERTY.
static java.lang.Integer	POLICY_RELOAD_LINKS value for the CACHE_POLICY_PROPERTY (default).
static java.lang.String	PREFERRED_LANGUAGES_PROPERTY type is String[]
static int	VACUUM_FLAG_DONT_SAVE_RECENT_LINK when used in conjunction with VACUUM_FLAG_LINKS, forces the removal of the most recent Link.
static int	VACUUM_FLAG_LINKS cleans up any Octopus Link which expiration date has passed except the most recent one for each type
static int	VACUUM_FLAG_NODES cleans up any Octopus Node which expiration date has passed
static int	VACUUM_FLAG_SEASHELL cleans up Seashell Objects which expiration date has passed
static int	VACUUM_FLAG_WIPE use with caution! Wipes all the objects except the Personality.
static java.lang.String	VERSION_PROPERTY type is Integer

Constructor Summary

Constructors

Constructor and Description
Engine() Create a new instance of the Engine class.

Method Summary

Methods

Modifier and Type	Method and Description
void	addTransactionListener(TransactionListener listener) adds a transaction listener.
void	destroy() destroys the engine.
java.lang.String[]	getLinkIds() gets all the IDs of the Links that the engine has access to
java.lang.String[]	getNodeIds() gets all the IDs of the Nodes that the engine has access to
Attribute	getObjectDetails(java.lang.String objectId) returns detailed information about the Object whose ID is specified such as its attributes and more.
java.lang.Object	getProperty(java.lang.String name) gets the value of a property of the engine.
java.lang.String[]	getPropertyNames() gets all the engine property name
Service[]	getServices() gets the list of the services that are currently configured for this engine.
DateTime	getTrustedTime() gets the current value of the trusted time
boolean	isPersonalized() indicates whether or not this engine has been personalized
void	personalize(java.lang.String personalizationToken) requests that the engine engage in the personalization process.
void	processServiceToken(java.lang.String actionToken) requests that the engine process a service token.
void	removeTransactionListener(TransactionListener listener) removes a transaction listener.
void	setProperty(java.lang.String name, java.lang.Object property) sets the value of a property of the engine.
java.lang.String	transformUriTemplate(java.lang.String template) transforms a URI template according to the "URI Templates for Marlin" specification
void	updatePersonality(java.lang.String updatePersonalityToken) requests that the engine engage in the update personality.
void	updateSecurityData(java.lang.String serviceId, int lastUpdate) updates security data for a specified service configured for this engine object
void	vacuumData(int flags) removes expired data stored in the DRM database.

Methods inherited from class java.lang.Object

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

Field Detail

VACUUM_FLAG_NODES

public static final int VACUUM_FLAG_NODES

cleans up any Octopus Node which expiration date has passed

See Also:

Constant Field Values

VACUUM_FLAG_LINKS

public static final int VACUUM_FLAG_LINKS

cleans up any Octopus Link which expiration date has passed except the most recent one for each type

See Also:

Constant Field Values

VACUUM_FLAG_SEASHELL

public static final int VACUUM_FLAG_SEASHELL

cleans up Seashell Objects which expiration date has passed

See Also:

Constant Field Values

VACUUM_FLAG_DONT_SAVE_RECENT_LINK

public static final int VACUUM_FLAG_DONT_SAVE_RECENT_LINK

when used in conjunction with VACUUM_FLAG_LINKS, forces the removal of the most recent Link.

See Also:

Constant Field Values

VACUUM_FLAG_WIPE

public static final int VACUUM_FLAG_WIPE

use with caution! Wipes all the objects except the Personality. Could be used when reselling a device.

See Also:

Constant Field Values

POLICY_DO_NOT_RELOAD_LINKS

public static final java.lang.Integer POLICY_DO_NOT_RELOAD_LINKS

value for the CACHE_POLICY_PROPERTY. If set, the engine will not try to reload all the Links during license evaluation.

POLICY_RELOAD_LINKS

public static final java.lang.Integer POLICY_RELOAD_LINKS

value for the CACHE_POLICY_PROPERTY (default). If set, the engine will try to reload all the Links during license evaluation

BUILD_DATE_PROPERTY

public static final java.lang.String BUILD_DATE_PROPERTY

build date property. type is String

See Also:

Constant Field Values

CACHE_POLICY_PROPERTY

public static final java.lang.String CACHE_POLICY_PROPERTY

tells how links are cached. By default, the policy is CACHE_POLICY_RELOAD_LINKS. type is Integer

See Also:

Constant Field Values

HTTP_CONNECTION_TIMEOUT_PROPERTY

public static final java.lang.String HTTP_CONNECTION_TIMEOUT_PROPERTY

type is Integer

See Also:

Constant Field Values

HTTP_IO_TIMEOUT_PROPERTY

public static final java.lang.String HTTP_IO_TIMEOUT_PROPERTY

type is Integer

See Also:

Constant Field Values

HTTP_PROXY_ENABLED_PROPERTY

public static final java.lang.String HTTP_PROXY_ENABLED_PROPERTY

type is Boolean

See Also:

Constant Field Values

HTTP_PROXY_HOST_NAME_PROPERTY

public static final java.lang.String HTTP_PROXY_HOST_NAME_PROPERTY

type is String

See Also:

Constant Field Values

HTTP_PROXY_PORT_PROPERTY

public static final java.lang.String HTTP_PROXY_PORT_PROPERTY

type is Integer

See Also:

Constant Field Values

HTTP_PROXY_SYSTEM_DEFAULT_PROPERTY

public static final java.lang.String HTTP_PROXY_SYSTEM_DEFAULT_PROPERTY

type is Boolean

See Also:

Constant Field Values

HTTPS_PROXY_HOST_NAME_PROPERTY

public static final java.lang.String HTTPS_PROXY_HOST_NAME_PROPERTY

type is String

See Also:

Constant Field Values

HTTPS_PROXY_PORT_PROPERTY

public static final java.lang.String HTTPS_PROXY_PORT_PROPERTY

type is Integer

See Also:

Constant Field Values

IS_PERSONALIZED_PROPERTY

public static final java.lang.String IS_PERSONALIZED_PROPERTY

type is Boolean

See Also:

Constant Field Values

PERSONALITY_PROPERTY

public static final java.lang.String PERSONALITY_PROPERTY

type is com.intertrust.wasabi.Attribute

See Also:

Constant Field Values

NEMO_PROPERTY

public static final java.lang.String NEMO_PROPERTY

type is com.intertrust.wasabi.Attribute

See Also:

Constant Field Values

PREFERRED_LANGUAGES_PROPERTY

public static final java.lang.String PREFERRED_LANGUAGES_PROPERTY

type is String[]

See Also:

Constant Field Values

VERSION_PROPERTY

public static final java.lang.String VERSION_PROPERTY

type is Integer

See Also:

Constant Field Values

Constructor Detail

Engine

public Engine()
       throws ErrorCodeException

Create a new instance of the Engine class.

Note that having a listener that properly detects any transaction failure is essential for the error handling in the client application code. See TransactionListener for pseudo code of a listener that captures any transaction failure.

Throws:

ErrorCodeException

Method Detail

getLinkIds

public java.lang.String[] getLinkIds()
                              throws ErrorCodeException

gets all the IDs of the Links that the engine has access to

Returns:

the link IDs

Throws:

ErrorCodeException

getNodeIds

public java.lang.String[] getNodeIds()
                              throws ErrorCodeException

gets all the IDs of the Nodes that the engine has access to

Returns:

the node IDs

Throws:

ErrorCodeException

getPropertyNames

public java.lang.String[] getPropertyNames()
                                    throws ErrorCodeException

gets all the engine property name

Returns:

the property names

Throws:

ErrorCodeException

getTrustedTime

public DateTime getTrustedTime()
                        throws ErrorCodeException

gets the current value of the trusted time

Returns:

the trusted time

Throws:

ErrorCodeException

isPersonalized

public boolean isPersonalized()

indicates whether or not this engine has been personalized

Returns:

true if the Engine is personalized, false otherwise.

personalize

public void personalize(java.lang.String personalizationToken)
                 throws ErrorCodeException,
                        java.lang.NullPointerException

requests that the engine engage in the personalization process. If one or more transaction listeners have been set. these will be called during the transaction.

Note that having a listener that properly detects any transaction failure is essential for the error handling in the client application code. See TransactionListener for pseudo code of a listener that captures any transaction failure.

Parameters:

personalizationToken - can be null

Throws:

ErrorCodeException - if the engine has already been personalized

java.lang.NullPointerException - if the the personalizationToken parameter is null

updatePersonality

public void updatePersonality(java.lang.String updatePersonalityToken)
                       throws ErrorCodeException

requests that the engine engage in the update personality. If one or more transaction listeners have been set. these will be called during the transaction.

Note that having a listener that properly detects any transaction failure is essential for the error handling in the client application code. See TransactionListener for pseudo code of a listener that captures any transaction failure.

Parameters:

updatePersonalityToken - can be null

Throws:

ErrorCodeException - if the engine is not able to update personality

Since:

1.19

processServiceToken

public void processServiceToken(java.lang.String actionToken)
                         throws ErrorCodeException

requests that the engine process a service token. If one or more transaction listeners have been set, these will be called during the transaction

Note that having a listener that properly detects any transaction failure is essential for the error handling in the client application code. See TransactionListener for pseudo code of a listener that captures any transaction failure.

Parameters:

actionToken - cannot be null

Throws:

ErrorCodeException - if the transaction cannot be launched

java.lang.NullPointerException - if the actionToken parameter is null

transformUriTemplate

public java.lang.String transformUriTemplate(java.lang.String template)
                                      throws ErrorCodeException,
                                             java.lang.NullPointerException

transforms a URI template according to the "URI Templates for Marlin" specification

Parameters:

template - cannot be null

Returns:

the URI resulting of the transformed template

Throws:

ErrorCodeException

java.lang.NullPointerException - if the template paratemer is null

updateSecurityData

public void updateSecurityData(java.lang.String serviceId,
                      int lastUpdate)
                        throws ErrorCodeException,
                               java.lang.NullPointerException

updates security data for a specified service configured for this engine object

Note that having a listener that properly detects any transaction failure is essential for the error handling in the client application code. See TransactionListener for pseudo code of a listener that captures any transaction failure.

Parameters:

serviceId - ID of the service whose security data will be updated (cannot be null)

lastUpdate - if an update has occurred within the last lastUpdate seconds, the security data will not be updated when the function is called. Callers can pass 0 to mean update regardless of the when the last update occurred.

Throws:

ErrorCodeException

java.lang.NullPointerException - if the serviceId parameter is null

vacuumData

public void vacuumData(int flags)
                throws ErrorCodeException

removes expired data stored in the DRM database.

Parameters:

flags - a combination of flags (example: VACUUM_FLAG_NODES|VACUUM_FLAG_LINKS)

Throws:

ErrorCodeException

getObjectDetails

public Attribute getObjectDetails(java.lang.String objectId)
                           throws ErrorCodeException,
                                  java.lang.NullPointerException

returns detailed information about the Object whose ID is specified such as its attributes and more.

Parameters:

objectId - the ID of the requested Octopus Object. Cannot be null.

Returns:

attribute tree containing the detailed information

Throws:

ErrorCodeException - if this object is not found

java.lang.NullPointerException - if the objectId parameter is null

getServices

public Service[] getServices()
                      throws ErrorCodeException

gets the list of the services that are currently configured for this engine.

Returns:

the array of Services attached to this Engine

Throws:

ErrorCodeException

getProperty

public java.lang.Object getProperty(java.lang.String name)
                             throws ErrorCodeException,
                                    java.lang.NullPointerException

gets the value of a property of the engine. The type of the property should be known by the caller (documented in this API).

Parameters:

name - the property name (cannot be null)

Returns:

the property value

Throws:

ErrorCodeException - if the property does not exist

java.lang.NullPointerException - if the name parameter is null

setProperty

public void setProperty(java.lang.String name,
               java.lang.Object property)
                 throws ErrorCodeException,
                        java.lang.NullPointerException

sets the value of a property of the engine.

Parameters:

name - name of the property (cannot be null)

property - value of the property (cannot be null)

Throws:

ErrorCodeException - if this property does not exist, cannot be set or if the value is of the wrong type

java.lang.NullPointerException - if any of the parameters is null

destroy

public void destroy()

destroys the engine. Should be called in the finally clause when the engine is used. The engine is no more valid after this method has been called.

addTransactionListener

public void addTransactionListener(TransactionListener listener)
                            throws java.lang.NullPointerException

adds a transaction listener. WARNING: If this method is called in the listener method implementations, the added listener will be called for the next event to come and not the current one.

Note that having a listener that properly detects any transaction failure is essential for the error handling in the client application code. See TransactionListener for pseudo code of a listener that captures any transaction failure.

Parameters:

listener - (cannot be null)

Throws:

java.lang.NullPointerException - if the listener parameter is null

removeTransactionListener

public void removeTransactionListener(TransactionListener listener)
                               throws java.lang.NullPointerException

removes a transaction listener. WARNING: If this method is called in the listener method implementations. the removed listener will still be called for the current event.

Note that having a listener that properly detects any transaction failure is essential for the error handling in the client application code. See TransactionListener for pseudo code of a listener that captures any transaction failure.

Parameters:

listener - (cannot be null)

Throws:

java.lang.NullPointerException - if the listener parameter is null