记帐 API

Sun Java System Content Delivery Server 记帐 API 提供 Content Delivery Server 与记帐系统之间的接口。使用记帐 API 可以定制创建支持预付记帐或异步记帐的记帐适配器。

有关这些类的其他信息，请参见 $CDS_HOME/javadoc/cdsapi/index.html 处的 Javadoc 工具的 HTML 输出。

3.1 一般处理流程

记帐 API 用于处理 Content Delivery Server 与外部记帐系统之间的通信。记帐事务的详细资料保留在 BillingInfo 对象中。记帐适配器是 BillingManager 接口的实现，它用于确定事务的处理方式。

本节介绍以下 Content Delivery Server 与外部记帐系统之间的信息流：

3.1.1 内容列表

订户请求可用内容列表或 Vending Manager 管理员请求储存内容列表时将启动该列表进程。图 2 显示了此进程。

3.1.2 事务启动

当订户单击内容项目旁边的“查看详细资料”时，记帐事务将启动。图 3 显示了此进程。

3.1.3 订户购买

当用户选择项目并单击“购买”时，购买进程将启动。购买进程将使用启动事务时创建的 BillingInfo 对象。图 4 显示了此进程。

订户购买内容时，与事务关联的 BillingInfo 对象存储在 Content Delivery Server 数据库中。如有任何进一步操作需要记帐信息，Content Delivery Server 就会以订户 ID 和内容 ID 为关键字从数据库中检索对象。

3.1.4 下载确认

当设备完成下载并通知 Content Delivery Server 时，确认进程将启动。图 5 显示了此进程。如果下载成功并且记帐系统不需要通知，则不执行任何操作。

3.1.5 订阅验证

当订户在订阅期结束后访问内容时，订阅验证进程将启动。图 6 显示了此进程。

3.1.6 错误处理

当记帐系统检测到错误时，将向订户显示普通错误消息。通过在由 BillingManager 接口的实现返回的 BillingInfo 对象中设置回复消息，可以定制此消息以显示附加信息。只要记帐适配器检测到错误，即调用 setOK() 将 BillingInfo 对象中的 "OK" 标志设置为 false，并调用 setReplyMessage() 设置向订户显示的消息。

3.2 BillingManager 接口

BillingManager 接口根据 BillingInfo 对象中包含的事务详细资料处理记帐事务。实现 BillingManager 以创建系统的记帐适配器。记帐适配器是 Content Delivery Server 与记帐系统之间的接口。

3.2.1 authorize()

abstract BillingInfo authorize(BillingInfo inBillingInfo, boolean[] inNeedToAuthorizeBillingModel)

如果外部记帐系统需要对事务进行授权，则当订户单击项目旁边的“购买”按钮时，此方法将被 Content Delivery Server 调用。要表明需要授权，BillingInfo 对象中的 "Authorize Needed" 标志必须由 getBillingInfo() 进行设置。

使用此方法可以确定订户是否经过授权购买所需内容。如果记帐系统支持预付记帐模型，则使用此方法可以检验订户帐户中是否有足够的余额购买该内容。

参数 inNeedToAuthorizeBillingModel 提供了按 BillingConstants 类中定义的记帐模型常数进行编索的标志数组。这些常数是

每个标志都表明授权事务时是否应考虑记帐模型。例如，以下参数已给定：

将按 DOWNLOAD 编索的标志设置为 false，以表明无需为此事务收取下载费用。因此，授权该事务时无需考虑下载费用。根据系统的需要使用或忽略这些标志。

如果订户被授权购买内容，则可以在将 BillingInfo 对象返回到 Content Delivery Server 之前调用 setIsOK()，以便将 BillingInfo 对象中的 "OK" 标志设置为 true。如果不允许订户购买该内容，则将 "OK" 标志设置为 false。

如果未通过 getBillingInfo() 设置 BillingInfo 对象中的 "Confirm Needed" 标志，则可以通过调用 setConfirmNeeded() 来设置该标志。如果希望在内容成功下载到设备时通知记帐系统，请将该标志设置为 true。如果不希望通知记帐系统，请将该标志设置为 false。

3.2.2 checkSubscription()

abstract BillingInfo checkSubscription(BillingInfo inBillingInfo) throws BillingException

如果订户试图在订阅期结束后使用内容，Content Delivery Server 将调用此方法。使用该方法可以在订阅在 Content Delivery Server 外部终止时通知 Content Delivery Server。

此方法应通过调用 BillingInfo 对象的 setSubscriptionTerminated() 方法设置 "Subscription Terminated"标志。要表明订阅已终止，请将该标志设置为 true。然后订户将收到更新订阅的提示。要表明订阅仍然有效，请将该标志设置为 false。然后在下一期间将自动更新此订阅。

3.2.3 confirm()

abstract void confirm(BillingInfo inBillingInfo)

如果外部记帐系统要求收到下载成功的通知，Content Delivery Server 收到订户设备的下载确认后将调用此方法。要表明需要确认，BillingInfo 对象中的 "Confirm Needed" 标志必须由 getBillingInfo() 或 authorize() 进行设置。

确认内容已下载后，可以使用此方法执行所需的操作。例如，您可能希望仅在收到下载成功的确认后从订户帐户扣除金额。

3.2.4 getBillingInfo()

abstract BillingInfo getBillingInfo(BillingInfo inBillingInfo)

此方法在订户请求项目的详细资料或购买项目时由 Content Delivery Server 调用。Content Delivery Server 创建 BillingInfo对象并将其传递给此方法，该对象包括记帐信息。

使用此方法可以根据需要修改记帐信息，并将修改过的 BillingInfo 对象返回到 Content Delivery Server。例如，要向选定订户提供折扣，请更改 Content Delivery Server 指定的价格。

此方法应通过调用 BillingInfo 对象的 setAuthorizeNeeded() 方法设置 "Authorize Needed" 标志。如果希望记帐系统验证订户是否被授权购买选定内容，请将该标志设置为 true。如不希望对订户进行预授权，请将该标志设置为 false。

如果将 "Authorize Needed" 标志设置为 false，请在此方法中设置 "Confirm Needed" 标志和 "OK" 标志。如果希望在内容成功下载到设备时通知记帐系统，请通过调用 setConfirmNeeded() 将 "Confirm Needed" 标志设置为 true。如果不希望通知记帐系统，请将该标志设置为 false。

要使订户能够在 "Authorize Needed" 标志为 false 时购买内容，请通过调用 setOK() 将 "OK" 标志设置为 true。如果将 "OK" 标志设置为 false 并且 "Authorize Needed" 标志也是 false，订户将不能下载指定内容。如果 "Authorize Needed" 标志设置为 true，则 "OK" 标志应在 authorize() 中进行设置。

3.2.5 getBillingInfos()

abstract BillingInfo[] getBillingInfos(BillingInfo[] inBillingInfos)

当订户请求可用内容列表或 Vending Manager 管理员请求储存内容列表时，此方法将由 Content Delivery Server 调用。Content Delivery Server 创建 BillingInfo 对象列表并将其传递给此方法，该对象包括记帐信息。

使用此方法可以根据需要修改记帐信息，并将修改过的 BillingInfo 对象列表返回到 Content Delivery Server。例如，要提供折扣，请更改 Content Delivery Server 指定的价格。

此方法应通过调用列表中的每个 BillingInfo 对象的 setAuthorizeNeeded() 方法设置 "Authorize Needed" 标志。如果希望记帐系统验证订户是否被授权购买选定内容，请将该标志设置为 true。如不希望对订户进行预授权，请将该标志设置为 false。

要使订户能够在 "Authorize Needed" 标志为 false 时购买内容，请通过调用 setOK() 将 "OK" 志设置为 true。如果将 "OK" 志设置为 false 并且 "Authorize Needed" 标志也是 false，订户将不能下载指定内容。如果 "Authorize Needed" 标志设置为 true，则 "OK" 志应在 authorize() 中进行设置。

3.2.6 getLog()

protected static com.sun.content.server.log.LogCategory getLog()

此方法返回 LogCatetory 对象，用于记录记帐 API 生成的错误和警告消息。使用此方法可以获得应在处理 Content Delivery Server 中的记帐事务时用于记录错误和其他信息的日志文件。

3.2.7 refund()

abstract void refund(BillingInfo inBillingInfo)

此方法将在客户服务代理使用 Vending Manager 管理控制台退还订户购买费用时由 Content Delivery Server 调用。Content Delivery Server 通过存储在数据库中的记帐信息为原始记帐事务创建 BillingInfo 对象，并将其传递给此方法。

3.2.8 reverse()

abstract void reverse(BillingInfo inBillingInfo)

此方法在将内容无法下载到订户设备时由 Content Delivery Server 调用。Content Delivery Server 通过存储在数据库中的记帐信息为原始记帐事务创建 BillingInfo 对象，并将其传递给此方法。

使用此方法可以取消记帐事务，因此订户便无需为该内容付费。

3.2.9 subscribe()

abstract void subscribe(BillingInfo inBillingInfo)

此方法在订户开始订阅内容时由 Content Delivery Server 调用。Content Delivery Server 通过存储在数据库中的记帐信息为原始记帐事务创建 BillingInfo 对象，并将其传递给此方法。

使用此方法可以为订户启动订阅。如果订阅重复出现，则此方法仅在订阅启动时调用一次。当每次订阅期结束时，记帐系统应自动向订户收取费用。如果订阅不重复出现，则在每次订户更新订阅时调用该方法。

3.2.10 unsubscribe()

abstract void unsubscribe(BillingInfo inBillingInfo)

此方法在订户取消重复出现的订阅时由 Content Delivery Server 调用。Content Delivery Server 通过存储在数据库中的记帐信息为原始记帐事务创建 BillingInfo 对象，并将其传递给此方法。

3.3 使用记帐 API

记帐 API 的类可以在 cdsapi.jar（位于 $CDS_HOME/deployment/deployment-name/lib/cdslib 目录）中找到。

module.security.billingmanager=com.sun.content.server.billing.external.MyBillingManager

3.4 示例

package com.sun.content.server.billing.external; 
 
import com.sun.content.server.billing.BillingException; 
import com.sun.content.server.billing.BillingInfo; 
import com.sun.content.server.billing.BillingManager; 
import com.sun.content.server.log.BillingManagerKeys; 
import com.sun.content.server.log.LogCategory; 
 
/** 
 * This is a sample implementation of the Billing API. 
 */ 
public class CDSBillingManager implements BillingManager 
{ 
  // These flags can be used to simulate responses from the billing 
  //integration. 
  public static final int SUCCESS = 0; 
  public static final int EXCEPTION = 1; 
  public static final int BILLING_EXCEPTION = 2; 
  public static final int UNAUTHORIZED = 3; 
  public static final int NULL = 4; 
 
  // by default everything will pass through fine 
  // but you can change these at runtime. 
  public static int AUTHORIZE_RESPONSE = SUCCESS; 
  public static int GET_BILLING_INFO_RESPONSE = SUCCESS; 
  public static int GET_BILLING_INFOS_RESPONSE = SUCCESS; 
  public static int CONFIRM_RESPONSE = SUCCESS; 
  public static int DELETE_RESPONSE = SUCCESS; 
  public static int REFUND_RESPONSE = SUCCESS; 
  public static int REVERSE_RESPONSE = SUCCESS; 
  public static int SUBSCRIBE_RESPONSE = SUCCESS; 
  public static int UNSUBSCRIBE_RESPONSE = SUCCESS; 
  public static int CHECK_SUBSCRIPTION_RESPONSE = SUCCESS; 
 
  /** 
   * This is used to log debug, warning, and error messages to the 
   * logging system. 
   */ 
  private static final LogCategory sLog = 
    LogCategory.getLog("BillingManager"); 
 
  /** 
   * see BillingManager#getBillingInfo(BillingInfo) 
   */ 
  public BillingInfo getBillingInfo(BillingInfo inBillingInfo) 
         throws BillingException 
  { 
    if (GET_BILLING_INFO_RESPONSE == NULL) 
      return null; 
 
    if (GET_BILLING_INFO_RESPONSE == EXCEPTION) 
      throw new NullPointerException("Developer Null Pointer"); 
 
    if (GET_BILLING_INFO_RESPONSE == BILLING_EXCEPTION) 
      throw new BillingException("Developer Billing Exception"); 
 
    // Set IsAuthorizeNeeded flag 
    inBillingInfo.setAuthorizeNeeded(true); 
    return inBillingInfo; 
  } 
 
  /** 
   * see BillingManager#getBillingInfos(BillingInfo[]) 
   */ 
  public BillingInfo[]  
    getBillingInfos(BillingInfo[] inBillingInfos)  
    throws BillingException 
  { 
      for (int index = 0; index < inBillingInfos.length; index++) 
    { 
      // Set IsAuthorizeNeeded flag 
      inBillingInfos[index].setAuthorizeNeeded(true); 
    } 
 
    if (GET_BILLING_INFOS_RESPONSE == NULL) 
      return null; 
 
    if (GET_BILLING_INFOS_RESPONSE == EXCEPTION) 
      throw new NullPointerException("Testing Null Pointer"); 
 
    if (GET_BILLING_INFOS_RESPONSE == BILLING_EXCEPTION) 
      throw new BillingException("Testing Billing Exception"); 
 
    return inBillingInfos; 
  } 
 
  /** 
   * see.BillingManager#authorize(BillingInfo, boolean[]) 
   */ 
  public BillingInfo authorize(BillingInfo inBillingInfo,  
         boolean[] inNeedToAuthorizeBillingModel) 
         throws BillingException 
  { 
    if (AUTHORIZE_RESPONSE == NULL) 
      return null; 
 
    if (AUTHORIZE_RESPONSE == EXCEPTION) 
      throw new NullPointerException("Testing Null Pointer"); 
 
    if (AUTHORIZE_RESPONSE == BILLING_EXCEPTION) 
     throw new BillingException("Testing Billing Exception"); 
 
    if (AUTHORIZE_RESPONSE == UNAUTHORIZED) 
    { 
      inBillingInfo.setOk(false); 
      inBillingInfo.setReplyMessage("You are not authorized"); 
      return inBillingInfo; 
    } 
 
// Set IsOk and IsConfirmNeeded flags 
    inBillingInfo.setConfirmNeeded(true); 
    inBillingInfo.setOk(true); 
 
    return inBillingInfo; 
  } 
 
  /** 
   * seeBillingManager#confirm(BillingInfo) 
   */ 
  public void confirm(BillingInfo inBillingInfo) 
      throws BillingException 
  { 
    if (CONFIRM_RESPONSE == EXCEPTION) 
      throw new NullPointerException("Developer Null Pointer"); 
 
    if (CONFIRM_RESPONSE == BILLING_EXCEPTION) 
      throw new BillingException("Developer Billing Exception"); 
  } 
 
  /** 
   * see BillingManager#reverse(BillingInfo) 
   */ 
  public void reverse(BillingInfo inBillingInfo) 
      throws BillingException 
  { 
    if (REVERSE_RESPONSE == EXCEPTION) 
      throw new NullPointerException("Developer Null Pointer"); 
 
    if (REVERSE_RESPONSE == BILLING_EXCEPTION) 
      throw new BillingException("Developer Billing Exception"); 
  } 
 
  /** 
   * see BillingManager#refund(BillingInfo) 
   */ 
  public void refund(BillingInfo inBillingInfo) 
      throws BillingException 
  { 
    if (REFUND_RESPONSE == EXCEPTION) 
      throw new NullPointerException("Developer Null Pointer"); 
 
    if (REFUND_RESPONSE == BILLING_EXCEPTION) 
      throw new BillingException("Developer Billing Exception"); 
  } 
 
  /** 
   * seeBillingManager#subscribe(BillingInfo) 
   */ 
  public void subscribe(BillingInfo inBillingInfo) 
      throws BillingException 
  { 
    if (SUBSCRIBE_RESPONSE == EXCEPTION) 
      throw new NullPointerException("Developer Null Pointer"); 
 
    if (SUBSCRIBE_RESPONSE == BILLING_EXCEPTION) 
       throw new BillingException("Developer Billing Exception"); 
  } 
 
  /** 
   * see BillingManager#unsubscribe(BillingInfo) 
   */ 
  public void unsubscribe(BillingInfo inBillingInfo) 
      throws BillingException 
  { 
    if (UNSUBSCRIBE_RESPONSE == EXCEPTION) 
      throw new NullPointerException("Developer Null Pointer"); 
 
    if (UNSUBSCRIBE_RESPONSE == BILLING_EXCEPTION) 
      throw new BillingException("Developer Billing Exception"); 
  } 
 
  /** 
   * see BillingManager#checkSubscription(BillingInfo) 
   */ 
  public BillingInfo checkSubscription(BillingInfo inBillingInfo) 
      throws BillingException 
  { 
    if (CHECK_SUBSCRIPTION_RESPONSE == NULL) 
      return null; 
 
    if (CHECK_SUBSCRIPTION_RESPONSE == EXCEPTION) 
      throw new NullPointerException("Developer Null Pointer"); 
 
    if (CHECK_SUBSCRIPTION_RESPONSE == BILLING_EXCEPTION) 
      throw new BillingException("Developer Billing Exception"); 
 
    inBillingInfo.setSubscriptionTerminated(false); 
 
    return inBillingInfo; 
  } 
 
  /** 
   * see BillingManager#contentDelete(BillingInfo) 
   */ 
  public void contentDelete(BillingInfo inBillingInfo) 
      throws BillingException 
  { 
    if (DELETE_RESPONSE == EXCEPTION) 
     throw new NullPointerException("Developer Null Pointer"); 
 
    if (DELETE_RESPONSE == BILLING_EXCEPTION) 
     throw new BillingException("Developer Billing Exception"); 
  } 
}

第 3 章