第 10 章

订户 API

通过 Sun Java System Content Delivery Server 订户 API，可以访问由 Content Delivery Server 维护的数据。使用此 API 可以获取必要的数据来创建自己的客户机应用程序，以便订户访问由 Content Delivery Server 管理的内容。

以 Java 编程语言编写，位于具备 Content Delivery Server Subscriber Portal 的服务器上的客户机可以直接调用订户 API。如果编写客户机的语言不是 Java，或者客户机所在的服务器不包含 Content Delivery Server Subscriber Portal，那么客户机可以通过 XML-RPC（远程过程调用）实现来访问订户 API。

订户 API 包括客户机可能使用的以下类和接口：

ApiContextFactory：此类创建包含订户特征（例如语言环境、设备型号和移动 ID）的 IApiContext 对象。
ApiServiceFactory：此类为特定订户创建服务。通过服务可以访问相关信息的集合。例如，通过内容服务可以访问订户上次购物的列表、各个项目的详细资料和订户标记的内容。
ApiUtil：此类提供多种功能，例如启动事务或检查数据库版本。
IApiContext：此接口为当前订户提供信息。
ICategoryService：此接口提供对类别树和订户类别列表的访问。
IContentService：此接口提供对内容的访问，以便完成浏览、查找、检索和购买。
IDownloadService：此接口提供对内容描述符的访问。
IGiftingService：通过此接口订户可以将礼品或有关某一项的消息发送给其他订户。
IMessageService：通过此接口可以将消息发送给此订户或其他订户。消息可以是电子邮件、MMS、SMS 或 WAP 推送格式。
ISystemService：此接口提供对系统级内容的访问，例如语言环境、内容类型和设备型号。
IUserService：此接口提供对有关订户信息的访问并且可以创建新的订户帐户。
CDSException：此类是出现错误时订户 API 抛出的异常。

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

10.1 一般处理流程

本节介绍可能需要客户机应用程序执行的常规任务。本节中使用的类名是指构成订户 API 的 Java 类。如果您使用 XML-RPC 访问 Content Delivery Server 数据，则请参见第 10.3 节“XML-RPC 实现”以获得等效的处理程序信息。

通常，您为订户接口创建的客户机应用程序应包含多个操作，如下面列表中所述。

调用 ApiContextFactory 创建 IApiContext 对象。

IApiContext 对象说明特定订户或匿名订户。所有服务都使用此对象检索特定于对象所说明的订户的数据。通常，您应该为每个用户会话创建一个 IApiContext 对象，并将该对象存储在 HttpSession 对象中。有关样例代码，请参见第 10.2.2 节“IApiContext 对象创建示例”。

调用 ApiServiceFactory 来创建获得要使用的信息所需的服务。

创建的服务取决于要执行的任务。例如，要使某位订户能够为另一订户购买礼品，请创建 IGiftingService 对象。要为订户提供已购买内容的列表，请创建 IContentService 对象。要创建服务，必须具有 IApiContext 对象。创建的每个服务都提供特定于 IApiContext 对象所说明的订户的数据。有关样例代码，请参见第 10.2.3 节“创建服务的示例”。

调用所创建的服务方法检索要使用的信息。

例如，如果创建了 IContentService，则可以调用 getCampaigns() 获得订户可用活动列表，或调用 getPurchases() 获得订户已购买项目列表。

10.2 使用订户 API

订户 API 的类位于软件包 com.sun.content.server.subscriberapi 中。此软件包包含在 subscriberportal.jar 文件中，该文件位于以下某个位置：

对于 Sun Java System Application Server，该文件位于 $CDS_HOME/deployment/deployment-name/sun/domains/server-domain/server-name/applications/j2ee-modules/CDSSubscriberPortal_1/WEB-INF/lib。
对于 WebLogic Server，该文件位于 $CDS_HOME/deployment/deployment-name/weblogic/domains/server-domain/applications/subscriberportal/WEB-INF/lib。

其中，deployment-name 是部署 Catalog Manager 时指定的名称，server-domain 是在 app.server.domain 属性的配置文件中指定的值，server-name 是在 app.server.name 属性的配置文件中指定的值。

如果您的客户机应用程序是 Java 应用程序，那么请使用 subscriberportal.jar 文件中的订户 API 类创建您的客户机。编译应用程序时，此 JAR 文件必须位于类路径中。

要成功执行，包含客户机的 JAR 文件必须置于 $CDS_HOME/deployment/deployment-name/.../lib 目录中（该目录还包含 subscriberportal.jar 文件）。客户机必须运行在与随 Content Delivery Server 一起提供的 Subscriber Portal 相同的 web 应用程序结构中。不支持独立的 Java 应用程序。

如果客户机不是 Java 应用程序或者与 Content Delivery Server Subscriber Portal 不在同一台服务器上，请参见第 10.3 节“XML-RPC 实现”获取有关通过 XML-RPC 访问订户 API 的信息。

10.2.1 管理事务

每次创建服务实例并调用其方法来执行任务时，都会有事务发生。应用程序必须按照如下步骤中说明的方式管理 Content Delivery Server 事务：

有关样例实现，请参见第 10.2.2 节“IApiContext 对象创建示例”和第 10.2.3 节“创建服务的示例”中的代码示例。

10.2.2 IApiContext 对象创建示例

以下节选代码显示如何创建 IApiContext 对象。

... 
try 
{ 
  // Open a Transaction 
  ApiUtil.initTransaction(); 
 
  // Create a map of credentials (from user input) 
  Properties credentials = new Properties(); 
  credentials.put(ApiContextFactory.CREDENTIAL_USERNAME, username); 
  credentials.put(ApiContextFactory.CREDENTIAL_PASSWORD, password); 
 
  // Attempt to authenticate using the credentials 
  IApiContext apiContext = ApiContextFactory.createApiContext(credentials); 
 
  // Save the IApiContext in the HttpSession 
  session.setAttribute("API_CONTEXT", apiContext); 
 
  // Commit the Transaction 
  ApiUtil.commitTransaction(); 
} 
catch (MDSException e) 
{ 
  // Rollback the Transaction 
  ApiUtil.rollbackTransaction(); 
 
  // Evaluate the exception's error code 
  if(e.getErrorCode().equals(MDSException.MDS_EX_SUBSCRIBER_DISABLED) 
  { 
    // handle disabled user 
    ... 
  } 
  else 
  { 
    // handle API Exception 
    ... 
  } 
} 
finally 
{ 
  // clean up Transaction 
  ApiUtil.disposeTransaction(); 
} 
... 

10.2.3 创建服务的示例

以下节选代码显示如何创建内容服务以及如何使用该服务购买内容。

... 
try 
{ 
  // Open a Transaction 
  ApiUtil.initTransaction(); 
 
  // Retrieve the IApiContext from the HttpSession 
  IApiContext apiContext = (IApiContext) session.getAttribute("API_CONTEXT"); 
 
  // Get a reference to a Content Service 
  IContentService cs = ApiServiceFactory.getContentService(apiContext); 
 
  // Attempt to purchase a content item as part of a campaign 
  cs.purchaseContent(contentId, campaignId, true); 
 
  // Commit the Transaction 
  ApiUtil.commitTransaction(); 
} 
catch (MDSException e) 
{ 
  // Rollback the Transaction 
  ApiUtil.rollbackTransaction(); 
 
  // Handle API Exception 
  ... 
} 
finally 
{ 
  // Clean up Transaction 
  ApiUtil.disposeTransaction(); 
} 
... 

10.3 XML-RPC 实现

如果客户机不是 Java 应用程序，或者没有运行在具有 Content Delivery Server 的服务器上，则客户机需要使用 XML-RPC 与 Content Delivery Server 进行通信。通过 XML-RPC，客户机可以在进行传输和数据编码时分别使用 HTTP 和 XML 进行远程过程调用。通过使用 Internet 上的绑定，可以将 XML-RPC 与许多不同编程语言一起使用。订户 API 的所有这些功能通过 XML-RPC 才可以使用。

10.3.1 设置到 Content Delivery Server 的访问

要从 Content Delivery Server 获取数据，客户机必须可以与 Content Delivery Server 进行通信。请要求网络管理员确保客户机可以访问 Content Delivery Server，并且任何所需的代理或防火墙均已配置为允许该访问。

此外，Content Delivery Server 还必须认可客户机已授权执行数据请求。$CDS_HOME/deployment/deployment-name/conf/SubscriberPortal.properties 文件中的 subscriberApi.xml-rpc.trustedHosts 属性包含主机的列表，指明了哪些主机的请求将被接受。

将 subscriberApi.xml-rpc.trustedHosts 属性设置为客户机所在主机的主机名和 IP 地址，而不管是否与 Content Delivery Server 位于同一主机。要接受任何主机的请求，请保留此值为空。要接受多个主机的请求，请使用逗号分隔主机名或 IP 地址。例如，

subscriberApi.xml-rpc.trustedHosts=127.0.0.1,localhost 

10.3.2 使用订户 API 的 XML-RPC 处理程序

不论是直接访问订户 API 还是通过 XML-RPC 访问，应用程序的常规流（请参见第 10.1 节“一般处理流程”）都相同。XML-RPC 实现中的处理程序执行与订户 API 服务相同的功能。每个处理程序及其相应的服务都具备带有等效参数的等效方法。

本节介绍以下主题：

调用 XML-RPC 方法的指导
AuthenticationHandler
CategoryHandler
ContentHandler
DownloadHandler
GiftingHandler
MessageHandler
SystemHandler
UserHandler
方法的参数

10.3.2.1 调用 XML-RPC 方法的指导

请按以下指导原则编写处理程序调用代码。样例代码是使用 Java 语言编写的。

将调用的方法参数置于一个散列表中。将散列表置于向量中。

... 
// Set up the input parameters 
Vector parameters = new Vector(); 
Hashtable ht = new Hashtable(); 
ht.put("username", "user1"); 
ht.put("password", "cryptic1"); 
parameters.addElement(ht); 
... 

要调用方法，请传递方法的名称，以及为包含参数的散列表创建的向量。返回散列表。方法调用必须包含处理程序的名称，例如，AuthenticationHandler.getApiContext。

... 
// Send the request to Content Delivery Server 
Hashtable response = (Hashtable) client.execute("AuthenticationHandler.getApiContext", parameters); 
... 

通过检查返回的散列表中包含的响应代码，验证方法是否成功执行。如果发生错误，散列表中还包含响应消息。

... 
// Evaluate the response 
String errorCode = (String)response.get("response_code"); 
if (!errorCode.equals("1")) 
{ 
  // Handle Error 
  System.out.println((String)response.get("response_message")); 
} 

如果方法已成功执行，则提取散列表中返回的值。如果方法未返回任何值，则散列表只包含响应代码。

... 
  // Authentication successful 
  Hashtable apiContext = (Hashtable)response.get("apiContext"); 
  Integer subscriberId = (Integer)apiContext.get("subscriberId"); 
  String username = (String)apiContext.get("username"); 
  String localeCode = (String)apiContext.get("localeCode"); 
  String mobileId = (String)apiContext.get("mobileId"); 
  Integer modelId = (Integer)apiContext.get("modelId"); 
  ... 

以下几节介绍可以使用的处理程序。第 10.3.3 节“使用处理程序的示例”中提供示例。

10.3.2.2 AuthenticationHandler

AuthenticationHandler 等效于 APIContextFactory 类。该处理程序创建包含订户特征的对象。调用处理程序中的方法的指导在第 10.3.2.1 节“调用 XML-RPC 方法的指导”中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接。例如，

AuthenticationHandler.getApiContext 

下表介绍 AuthenticationHandler 方法。

10.3.2.3 CategoryHandler

CategoryHandler 等效于 ICategoryService 接口。通过此处理程序可以访问类别树和订户类别列表。调用处理程序中的方法的指导在第 10.3.2.1 节“调用 XML-RPC 方法的指导”中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接。例如，

CategoryHandler.getCategory 

下表介绍 CategoryHandler 方法。

10.3.2.4 ContentHandler

ContentHandler 等效于 IContentService 接口。通过此处理程序可以访问内容，以便完成浏览、查找、检索和购买。调用处理程序中的方法的指导在第 10.3.2.1 节“调用 XML-RPC 方法的指导”中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接。例如，

ContentHandler.browseContent 

下表介绍 ContentHandler 方法。

10.3.2.5 DownloadHandler

DownloadHandler 等效于 IDownloadService 接口。通过此处理程序可以访问下载内容所需描述符。调用处理程序中的方法的指导在第 10.3.2.1 节“调用 XML-RPC 方法的指导”中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接。例如，

DownloadHandler.downloadConfirm 

下表介绍 DownloadHandler 方法。

10.3.2.6 GiftingHandler

GiftingHandler 等效于 IGiftingService 接口。该处理程序将有关内容的礼品或通知发送到其他订户。调用处理程序中的方法的指导在第 10.3.2.1 节“调用 XML-RPC 方法的指导”中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接。例如，

GiftingHandler.createGifting 

下表介绍 GiftingHandler 方法。

10.3.2.7 MessageHandler

MessageHandler 等效于 IMessageService 接口。该处理程序将电子邮件、SMS、WAP 推送以及 MMS 消息发送到当前订户或其他订户。调用处理程序中的方法的指导在第 10.3.2.1 节“调用 XML-RPC 方法的指导”中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接。例如，

MessageHandler.sendMessageToSelf 

下表介绍 MessageHandler 方法。

10.3.2.8 SystemHandler

SystemHandler 等效于 ISystemService 接口。通过此处理程序可以访问系统级数据，例如内容类型，语言环境和型号。调用处理程序中的方法的指导在第 10.3.2.1 节“调用 XML-RPC 方法的指导”中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接。例如，

SystemHandler.getContentTypes 

下表介绍 SystemHandler 方法。

10.3.2.9 UserHandler

UserHandler 等效于 IUserService 接口。通过此处理程序可以访问订户的有关信息以及创建新的订户帐户。调用处理程序中的方法的指导在第 10.3.2.1 节“调用 XML-RPC 方法的指导”中进行了介绍。要调用方法，请将处理程序的名称与方法的名称相连接。例如，

UserHandler.getSubscriberId 

下表介绍 UserHandler 方法。

10.3.2.10 方法的参数

下表介绍方法的参数。容器对象（例如包含元素的散列表和向量）也在该表中进行介绍。

10.3.3 使用处理程序的示例

本节提供两个使用订户 API 的 XML-RPC 实现的示例。

10.3.3.1 ApiContext 对象创建示例

以下节选代码显示如何创建 ApiContext 对象。该样例使用 Java 编程语言的绑定。

... 
// Get a reference to the XmlRpcClient 
String url = "http://host1:8080/subscriber/xml_rpc.do"; 
XmlRpcClientLite client = new XmlRpcClientLite(url); 
 
// Set up the input parameters 
Vector parameters = new Vector(); 
Hashtable ht = new Hashtable(); 
ht.put("username", "user1"); 
ht.put("password", "cryptic1"); 
parameters.addElement(ht); 
 
// Send the request to Content Delivery Server 
Hashtable response = (Hashtable) client.execute("AuthenticationHandler.getApiContext", parameters); 
 
// Evaluate the response 
String errorCode = (String)response.get("response_code"); 
if (!errorCode.equals("1")) 
{ 
  // Handle Error 
  System.out.println((String)response.get("response_message")); 
  ... 
} 
else 
{ 
  // Authentication successful 
  Hashtable apiContext = (Hashtable)response.get("apiContext"); 
  Integer subscriberId = (Integer)apiContext.get("subscriberId"); 
  String username = (String)apiContext.get("username"); 
  String localeCode = (String)apiContext.get("localeCode"); 
  String mobileId = (String)apiContext.get("mobileId"); 
  Integer modelId = (Integer)apiContext.get("modelId"); 
  ... 
 
  // Save the ApiContext Hashtable in the Session 
  session.setAttribute("API_CONTEXT", apiContext); 
  ... 
} 
 
	... 
 

10.3.3.2 创建处理程序以及购买内容的示例

以下节选代码显示如何创建处理程序以及使用该处理程序购买内容。该样例使用 Java 编程语言的绑定。

... 
// Get a reference to the XmlRpcClient 
String url = "http://[[cds server host]]:[[cds server port]]/subscriber/xml_rpc.do"; 
XmlRpcClientLite client = new XmlRpcClientLite(url); 
 
// Retrieve the ApiContext Hashtable from the HttpSession 
Hashtable apiContext = (Hashtable) session.getAttribute("API_CONTEXT"); 
 
// Set up the input parameters 
Vector parameters = new Vector(); 
Hashtable ht = new Hashtable(); 
ht.put("apiContext", apiContext); 
ht.put("contentId", new Integer(1001)); 
ht.put("campaignId", new Integer(1000)); 
ht.put(“isSkipTrial? Boolean.TRUE); 
parameters.addElement(ht); 
 
// Send the request to Content Delivery Server 
Hashtable response = (Hashtable) client.execute("ContentHandler.purchaseContent", parameters); 
 
// Evaluate the response 
String errorCode = (String)response.get("response_code"); 
if (!errorCode.equals("1")) 
{ 
  // Handle Error 
  System.out.println((String)response.get("response_message")); 
  ... 
} 
else 
{ 
  // Purchase successful 
  ... 
} 
... 

定制指南 Sun Java™ System Content Delivery Server，版本 2004Q1

版权所有 © 2004 Sun Microsystems, Inc. 保留所有权利。必须依据许可证条款使用。