27 Subscriptions API

This chapter provides an overview of Subscriptions API and describes the use cases using this API.

This chapter contains the following sections:

27.1 Overview

The subscriptions API provides a mechanism for users to manage the assets to which a user is subscribed. Subscription, in this context, refers specifically to email subscriptions. Subscriptions created through this API are the equivalent of users clicking the Subscribe button on the asset detail page. Once a user subscribes to an asset, they are notified through email of events occurring on the asset. For a list of events for which subscribed users are notified, see the "Email Templates" section in Oracle Fusion Middleware User Guide for Oracle Enterprise Repository.

Using the subscriptions API of REX, developers can create, delete, and inspect subscriptions to lists of assets. The operations are always performed for the user identified in the authentication token passed as an argument to the various subscription methods.

27.2 Use Cases

This section describes the use cases using the Subscriptions API. It contains the following topics:

27.2.1 Use Case: Create Subscription to Assets

Description

  • Authenticate with REX.

  • Read a list of asset summaries through a query.

  • Subscribe to the matched assets.

Sample code is as follows:

package com.flashline.sample.subscriptionapi;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import com.flashline.registry.openapi.base.OpenAPIException;
import com.flashline.registry.openapi.entity.AssetSummary;
import com.flashline.registry.openapi.entity.AuthToken;
import com.flashline.registry.openapi.query.AssetCriteria;
import com.flashline.registry.openapi.service.v300.FlashlineRegistry;
import
 com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator;
public class CreateSubscription {
  public static void main(String pArgs[]) throws OpenAPIException,
      RemoteException, ServiceException {
    try {
      // /////////////////////////////////////////////////////////
      // Connect to Oracle Enterprise Repository
      // /////////////////////////////////////////////////////////
      URL lURL = null;
      lURL = new URL(pArgs[0]);
      FlashlineRegistry repository = new FlashlineRegistryServiceLocator()
          .getFlashlineRegistry(lURL);
      // /////////////////////////////////////////////////////////
      // Login to OER
      // /////////////////////////////////////////////////////////
      AuthToken authToken = repository.authTokenCreate(pArgs[1], pArgs[2]);
      // /////////////////////////////////////////////////////////
      // find the assets to which to subscribe
      // /////////////////////////////////////////////////////////
      AssetCriteria criteria = new AssetCriteria();
      criteria.setNameCriteria("%");
      AssetSummary[] lAssetSummaries = repository.assetQuerySummary(authToken,
          criteria);
      // /////////////////////////////////////////////////////////
      // Iterate through assets, pulling out the ids and adding
      // to the array of longs
      // /////////////////////////////////////////////////////////
      long[] lAssetIDs = new long[lAssetSummaries.length];
      for (int i = 0; i < lAssetSummaries.length; i++) {
        lAssetIDs[i] = lAssetSummaries[i].getID();
      }
      // /////////////////////////////////////////////////////////
      // Create the subscriptions. The value of "false" for the
      // parameter pFailOnAnyError, causes the operation to NOT
      // fail for any asset to which the user does not have VIEW
      // privileges, or for which the asset is not subscribable.
      //
      // If this value is not "false", the operation throws
      // an exception if any asset in the array of asset IDs is
      // not subscribable or viewable by the user, and NONE of the
      // subscriptions are recorded in the repository.
      // /////////////////////////////////////////////////////////
      repository.subscriptionCreate(authToken, lAssetIDs, false);
    } catch (OpenAPIException lEx) {
      System.out.println("ServerCode = " + lEx.getServerErrorCode());
      System.out.println("Message    = " + lEx.getMessage());
      System.out.println("StackTrace:");
      lEx.printStackTrace();
    } catch (RemoteException lEx) {
      lEx.printStackTrace();
    } catch (ServiceException lEx) {
      lEx.printStackTrace();
    } catch (MalformedURLException lEx) {
      lEx.printStackTrace();
    }
  }
}

27.2.2 Use Case: Delete Subscription to Assets

Description

  • Authenticate with REX.

  • Read a list of asset summaries through a query.

  • Delete any subscriptions that may exist for the matched assets.

Sample Code as follows:

package com.flashline.sample.subscriptionapi;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import com.flashline.registry.openapi.base.OpenAPIException;
import com.flashline.registry.openapi.entity.AssetSummary;
import com.flashline.registry.openapi.entity.AuthToken;
import com.flashline.registry.openapi.query.AssetCriteria;
import com.flashline.registry.openapi.service.v300.FlashlineRegistry;
import
 com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator;
public class DeleteSubscription {
  public static void main(String pArgs[]) throws OpenAPIException,
 RemoteException,
      ServiceException {
    try {
      ///////////////////////////////////////////////////////////
      // Connect to Oracle Enterprise Repository
      ///////////////////////////////////////////////////////////
      URL lURL = null;
      lURL = new URL(pArgs[0]);
      FlashlineRegistry repository = new FlashlineRegistryServiceLocator()
          .getFlashlineRegistry(lURL);
      ///////////////////////////////////////////////////////////
      // Login to OER
      ///////////////////////////////////////////////////////////
      AuthToken authToken = repository.authTokenCreate(
          pArgs[1],pArgs[2]);
      ///////////////////////////////////////////////////////////
      // find the assets for which to delete subscriptions
      ///////////////////////////////////////////////////////////
      AssetCriteria criteria = new AssetCriteria();
      criteria.setNameCriteria("%");
      AssetSummary[] lAssetSummaries = repository.assetQuerySummary(authToken,
 criteria);
      ///////////////////////////////////////////////////////////
      // Iterate through assets, pulling out the ids and adding
      // to the array of longs
      ///////////////////////////////////////////////////////////
      long[] lAssetIDs = new long[lAssetSummaries.length];
      for (int i = 0; i < lAssetSummaries.length; i++) {
        lAssetIDs[i] = lAssetSummaries[i].getID();
      }
      ///////////////////////////////////////////////////////////
      // Delete the subscriptions on the list of assets.
      ///////////////////////////////////////////////////////////
      repository.subscriptionDelete(authToken, lAssetIDs);
    } catch (OpenAPIException lEx) {
      System.out.println("ServerCode = " + lEx.getServerErrorCode());
      System.out.println("Message    = " + lEx.getMessage());
      System.out.println("StackTrace:");
      lEx.printStackTrace();
    } catch (RemoteException lEx) {
      lEx.printStackTrace();
    } catch (ServiceException lEx) {
      lEx.printStackTrace();
    } catch (MalformedURLException lEx) {
      lEx.printStackTrace();
    }
  }
}

27.2.3 Use Case: Read Subscriptions for Assets

Description

  • Authenticate with REX.

  • Read the list of subscribed assets for the authenticated user.

Sample Code is as follows:

package com.flashline.sample.subscriptionapi;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import com.flashline.registry.openapi.base.OpenAPIException;
import com.flashline.registry.openapi.entity.Asset;
import com.flashline.registry.openapi.entity.AuthToken;
import com.flashline.registry.openapi.service.v300.FlashlineRegistry;
import
 com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator;
public class ReadSubscriptions {
  public static void main(String pArgs[]) throws OpenAPIException,
 RemoteException,
      ServiceException {
    try {
      ///////////////////////////////////////////////////////////
      // Connect to Oracle Enterprise Repository
      ///////////////////////////////////////////////////////////
      URL lURL = null;
      lURL = new URL(pArgs[0]);
      FlashlineRegistry repository = new FlashlineRegistryServiceLocator()
          .getFlashlineRegistry(lURL);
      ///////////////////////////////////////////////////////////
      // Login to OER
      ///////////////////////////////////////////////////////////
      AuthToken authToken = repository.authTokenCreate(
          pArgs[1],pArgs[2]);
      //////////////////////////////////////////////////////////
      // Read all of the assets to which the user is subscribed.
      //////////////////////////////////////////////////////////
      long[] lSubscribedAssets =
 repository.subscriptionReadSubscribedAssets(authToken);
      //////////////////////////////////////////////////////////
      // Print out the assets to which the user is subscribed
      //////////////////////////////////////////////////////////
      Asset[] lAssets = repository.assetReadArray(authToken, lSubscribedAssets);
      System.out.println("Subscribed Assets for user "+pArgs[1]);
      for(int i=0; i<lAssets.length; i++){
        System.out.println("  -> "+lAssets[i].getLongName());
      }
    } catch (OpenAPIException lEx) {
      System.out.println("ServerCode = " + lEx.getServerErrorCode());
      System.out.println("Message    = " + lEx.getMessage());
      System.out.println("StackTrace:");
      lEx.printStackTrace();
    } catch (RemoteException lEx) {
      lEx.printStackTrace();
    } catch (ServiceException lEx) {
      lEx.printStackTrace();
    } catch (MalformedURLException lEx) {
      lEx.printStackTrace();
    }
  }
}

27.2.4 Use Case: Read Users Subscribed to an Asset

Description

  • Authenticate with REX.

  • Read the list of users subscribed to a particular asset.

Sample Code is as follows:

package com.flashline.sample.subscriptionapi;
import java.net.MalformedURLException;
import java.net.URL;
import java.rmi.RemoteException;
import javax.xml.rpc.ServiceException;
import com.flashline.registry.openapi.base.OpenAPIException;
import com.flashline.registry.openapi.entity.AssetSummary;
import com.flashline.registry.openapi.entity.AuthToken;
import com.flashline.registry.openapi.entity.RegistryUser;
import com.flashline.registry.openapi.query.AssetCriteria;
import com.flashline.registry.openapi.service.v300.FlashlineRegistry;
import
 com.flashline.registry.openapi.service.v300.FlashlineRegistryServiceLocator;
public class ReadSubscribersToAsset {
  public static void main(String pArgs[]) throws OpenAPIException,
 RemoteException,
      ServiceException {
    try {
      ///////////////////////////////////////////////////////////
      // Connect to Oracle Enterprise Repository
      ///////////////////////////////////////////////////////////
      URL lURL = null;
      lURL = new URL(pArgs[0]);
      FlashlineRegistry repository = new FlashlineRegistryServiceLocator()
          .getFlashlineRegistry(lURL);
      ///////////////////////////////////////////////////////////
      // Login to OER
      ///////////////////////////////////////////////////////////
      AuthToken authToken = repository.authTokenCreate(
          pArgs[1],pArgs[2]);
      //////////////////////////////////////////////////////////
      // Assume that this query returns some number of assets...
      //////////////////////////////////////////////////////////
      AssetCriteria lCriteria = new AssetCriteria();
      lCriteria.setNameCriteria("%");
      AssetSummary[] lAssetSummaries = repository.assetQuerySummary(authToken,
 lCriteria);
      //////////////////////////////////////////////////////////
      // Read the users that are subscribed to the first asset
      //////////////////////////////////////////////////////////
      RegistryUser[] lSubscribedUsers =
        repository.subscriptionReadUsersSubscribedToAsset(authToken,
 lAssetSummaries[0].getID());
      for (int i=0; i<lSubscribedUsers.length; i++){
        System.out.println("Subscribed Users:
 "+lSubscribedUsers[i].getUserName());
      }
    } catch (OpenAPIException lEx) {
      System.out.println("ServerCode = " + lEx.getServerErrorCode());
      System.out.println("Message    = " + lEx.getMessage());
      System.out.println("StackTrace:");
      lEx.printStackTrace();
    } catch (RemoteException lEx) {
      lEx.printStackTrace();
    } catch (ServiceException lEx) {
      lEx.printStackTrace();
    } catch (MalformedURLException lEx) {
      lEx.printStackTrace();
    }
  }
}