Skip navigation links

oracle.irm.engine.core.storage
Interface DesktopServices

public interface DesktopServices

Desktop services. Provides services that a user would typically perform on a desktop. When operations occur on the desktop licenses, classifications and cryptography key details are shipped to the desktop and stored locally in a DesktopStore. The licenses control how long these details are cached and determine such things as whether these licenses are stored on disk. When operations such as sealing, resealing or unsealing are performed this cache is automatically accessed or updated. The synchronization operation allows all rights to be obtained and cached. The check in operation release the use of these details so they can be used on another location (a different desktop). The desktop services are thread safe and it is valid for multiple threads and multiple users to use the services concurrently.

The desktop services can be used from J2SE applications using local libraries (license details stored and used locally) as well as being used remotely by accessing the J2EE sealing server application using web services (license details user and stored on a server).

Instance

The methods on DesktopServices can be invoked using DesktopServicesInstance.

Method Summary

boolean	checkForAvailableLicenses(Feature feature, Classification classification) Check that the authenticated account has a license.
void	checkIn(URI uri) Perform a check in for the specified server and update the store.
DesktopStore	getDesktopStore() The desktop store.
Collection<Classification>	listClassifications(URI uri) Lists classifications.
void	refresh(Classification classification, UUID uuid) Perform a license refresh and update the store.
void	request(Feature feature, Classification classification) Perform a request and update the store.
void	reset() Reset the store.
void	synchronize(URI uri) Perform a synchronize for the specified server and update the store.

Method Detail

getDesktopStore

DesktopStore getDesktopStore()

The desktop store. Contains a set of desktop bundles for all the servers contacted for the authenticated user.

Returns:

the value of the property. This method will never return null.

checkIn

void checkIn(URI uri)

Perform a check in for the specified server and update the store.

Checking in licenses

The following code demonstrates how to check in licenses checked out to the local device. These licenses can no longer be used from other locations (e.g. the Oracle IRM desktop or sealing server) until they expire or are manually checked in.

 import static oracle.irm.engine.core.storage.DesktopServicesInstance.checkIn;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.net.URI;
 
 public class CheckIn {
 
     public static void main(String[] args) {
 
         // The server URI is the first command line argument
         // e.g. https://irm.example.com/irm_desktop/request
         URI serverURI = URI.create(args[0]);
         
         // The username and password that will be used to contact the
         // IRM server are the last command line arguments
         final String username = args[1];
         final String password = args[2];
         
         // Configure an authenticator to provide the credentials
         // for the web service
         Authenticator.setDefault(new Authenticator() {
             @Override
             protected PasswordAuthentication getPasswordAuthentication() {
                 return new PasswordAuthentication(username, password.toCharArray());
             }
         });
 
         // Check in all the licenses currently within the
         // desktop store for the given server
         checkIn(serverURI);
     }

Parameters:

uri - the server URI.

synchronize

void synchronize(URI uri)
                 throws RepudiateException

Perform a synchronize for the specified server and update the store.

Synchronizing with a server to update the store

The following code demonstrates how to synchronize with a server using the synchronize method. The DesktopStore will be updated. The sample code displays the updated list of Classifications available to the user in the store.

 import static oracle.irm.engine.core.storage.DesktopServicesInstance.getDesktopStore;
 import static oracle.irm.engine.core.storage.DesktopServicesInstance.synchronize;
 
 import java.net.Authenticator;
 import java.net.PasswordAuthentication;
 import java.net.URI;
 import java.util.Collection;
 
 import oracle.irm.engine.core.classification.Classification;
 import oracle.irm.engine.core.general.Label;
 
 public class Synchronize {
 
     public static void main(String[] args) throws Exception {
         
         final String username = args[0];
         final String password = args[1];
         
         // Configure an authenticator to provide the credentials
         // for the web service
         Authenticator.setDefault(new Authenticator() {
             @Override
             protected PasswordAuthentication getPasswordAuthentication() {
                 return new PasswordAuthentication(username, password.toCharArray());
             }
         });
         
         // The server to synchronize with is the first command line
         // argument e.g. http://irm.example.com/irm_desktop/request
         URI serverURI = URI.create(args[2]);
 
         // Synchronize with the specified server
         synchronize(serverURI);
 
         Collection<Classification> classifications = getDesktopStore().getClassifications();
         
         // Display the labels of the classifications
         for (Classification classification : classifications) {
 
             for (Label label : classification.getLabels()) {
                 String name = label.getName();
 
                 System.out.println(name);
             }
         }
     }
 }

Parameters:

uri - the server URI.

Throws:

UpgradeRequiredException - the desktop must be upgraded before synchronization can complete.

RepudiateException - the desktop has been repudiated and is not allowed to complete a synchronization.

request

void request(Feature feature,
             Classification classification)
             throws UnknownClassificationException,
                    LicenseInUseException,
                    LicenseUnavailableException,
                    RepudiateException

Perform a request and update the store. The server is identified in the classification details.

Parameters:

feature - the feature being requested, such as opening or printing content.

classification - the content classification information.

Throws:

UnknownClassificationException - the content's classification is unknown to the server.

LicenseInUseException - the only licenses that are available are in use on another desktop.

LicenseUnavailableException - a license exists, but cannot be used for the specified feature and classification.

UpgradeRequiredException - the desktop must be upgraded before licenses can be requested.

RepudiateException - the desktop has been repudiated and is not allowed to complete a license request.

refresh

void refresh(Classification classification,
             UUID uuid)
             throws RepudiateException

Perform a license refresh and update the store.

Parameters:

classification - the content classification information.

uuid - the license UUID.

Throws:

RepudiateException - the desktop has been repudiated and is not allowed to complete a license request.

reset

void reset()

Reset the store. Reseting the store clears out all license and key information. Reseting does not check in licenses. The device details of the store are not affected by calling this method.

checkForAvailableLicenses

boolean checkForAvailableLicenses(Feature feature,
                                  Classification classification)
                                  throws UnknownClassificationException,
                                         LicenseInUseException,
                                         LicenseUnavailableException

Check that the authenticated account has a license. This method checks that there is at least one license available for the authenticated account to perform the feature on the provided classification. If no licenses are available locally, licenses will be requested from the IRM server.

Parameters:

feature - the application feature being requested.

classification - the classification being used.

Returns:

whether there is a license that is available that allows the specified feature to be used against the provided classification.

Throws:

UnknownClassificationException - the classification provided is known, but the exact instance of classification is unknown.

LicenseInUseException - a license exists, but is in use on another device.

LicenseUnavailableException - a license exists, but cannot be used for the specified feature and classification.

listClassifications

Collection<Classification> listClassifications(URI uri)

Lists classifications. This method returns the classification information that the authenticated user is allowed to use (e.g. filtered for the user based on their rights to open, seal, etc). To do this the server must synchronize licenses, so be aware than a check in may be required to release licenses for use on other devices.

Whether classification details are provided by this method is an implementation detail of the classification system. It may not be feasible for certain classification systems to list all classification details. e.g. for the Context classification system this method should list all the contexts that the user has been assigned rights.

Classification details are required when performing a sealing or resealing operation. Some of the information in the classification may not be known by the caller, so this method can be used to provide this additional classification information.

Parameters:

uri - the server URI.

Returns:

the classifications accessible to the authenticated user. If applicable, this method will return an empty collection rather than null to indicate no results.

Skip navigation links