名称

ChangeSynergy::apiSubscription


描述

预订列表将允许用户将自身标记为 CR 的订户。当用户请求成为 CR 的订户时,他们希望随时知悉 CR 更改。此类允许 API 获取并修改预订特定列表的用户。用于构造此类的实例的 XML 格式如下所示:

 <subscription>
	<subscriber>
		<username>
			user name
		</username>
		<email>
			user email
		</email>
		<realname>
			real name
		</realname>
	</subscriber>
	.
	.
	.
 </subscription>

方法

以下方法可用:

new
 sub new(xmlData)

初始化新创建的 ChangeSynergy::apiSubscription 类,以便使其表示传入的 xml 数据。

 my $subscription = new ChangeSynergy::apiSubscription(xmlData);
 
参数:
	xmlData  - 需要解析成可用格式的 XML 数据。
 抛出:

	die - 如果不能解析 xml 数据
addSubscriber

添加新订户到预订列表中。所有参数都是必需的。

注:该操作不会立即将订户添加到列表中。必须为 CR 更新 XML 信息后,该订户才会添加到列表中。 请参阅 getSubscription() 方法的 apiObjectData 类示例。

$subscription->addSubscriber("jsmith", "John Smith", "John.Smith@company.com");

 参数:
	userName - 要添加到预订列表中的用户的用户名。
	realName - 要添加到预订列表的用户的实名。
	eMail    - 要添加到预订列表中的用户的电子邮件地址。
 抛出:
 die - 如果提供的用户名已经被列表中的另一个用户使用了。
getSubscriber

根据对象数组中的位置获取一个订户数据对象。 返回的结果为 apiSubscriber 类的实例。

my $subscriber = $subscription->getSubscriber($iPos);

 参数:
	iPos - 用于检索数据的索引位置。
 返回:apiSubscriber
一个订户对象。	
getSubscriberByEmailAddress

根据订户电子邮件地址获取一个订户数据对象。 返回的结果为 apiSubscriber 类的实例。

注:反斜杠字符(“\”)必须用于转义 at 符号(“@”)。

my $subscriber = $subscription->getSubscriberByEmailAddress("John.Smith\@company.com");

 参数:
	email - 要检索的用户对象的电子邮件地址。
 返回:apiSubscriber
一个订户对象。		
抛出:

 die - 如果用户电子邮件地址不存在于预订列表中。
getSubscriberByRealName

根据订户实名获取一个订户数据对象。 返回的结果为 apiSubscriber 类的实例。

my $subscriber = $subscription->getSubscriberByRealName("John Smith");

 参数:
	realName - 要检索的用户对象的实名。
 返回:apiSubscriber
一个订户对象。		
抛出:

 die - 如果用户实名不存在于预订列表中。
getSubscriberByUserName

根据订户用户名获取一个订户数据对象。 返回的结果为 apiSubscriber 类的实例。

my $subscriber = $subscription->getSubscriberByUserName("u00001");

 参数:
	username - 要检索的用户对象的用户名。
 返回:apiSubscriber
一个订户对象。		
抛出:

 die - 如果用户名不存在于预订列表中。
getSubscriberSize

获取订户对象的数量。

my $subSize = $subscription->getSubscriberSize();

 返回:标量
此预订中的订户对象数量。	
getXmlData

获取构造 apiSubscription 对象所用的 XML 数据。

注意:仅适用于调试。

my $xmlData = $subscription->getXmlData();

 返回:标量
用于构造此对象的 XML 数据,非常适用于调试。  
toSubmitXml

获取发送给 IBM Rational Change 服务器以更新预订列表的 XML 数据。

my $xmlData = $subscription->toSubmitXml();

 返回:标量
发送到 IBM Rational Change 服务器的 XML 数据。