TMF814中迭代用法概述（SD1-15_iterators.pdf）

迭代用法概述

 

       本文包含如何使用迭代器的一个概述。

 

       迭代器是用在NMS的许多操作中，以便NMS可以方便的处理与之相关的大量返回数据。它们提供了一个批处理数据检索机制，批数据的大小是由NMS来指定的。

 

       在典型的情况下，一个NMS请求一个大小列表。根据这个要求，它可以指定在第一次回复中所能处理的最大对象数目，EMS所发送的数量要小于这个数值。EMS得到了当前需要返回对象的快照：以包含具有指定数目的对象列表作为回应，并且建立一个可以供NMS将来访问快照的对象迭代参考。

 

       这样的操作的通用形式如下：

 

 getAllObjectName(

(in qualifiers) /* some operations may supply qualifiers */

in unsigned long how_many,

out objectList list,

out iterator iteratorReference)

raises(globaldefs::ProcessingFailureException);

      

       how_many参数决定回应的最大数量，它是输出参数。IteratorReference提供了访问剩余对象，如果有的话。

 

       如果列表包含了全部的ObjectName对象，那么iteratorReference将是一个COBRA::Object::nil对象。如果还有更多，列表将包含EMS所知的第一批对象并且iteratorReference提供将来接入对象。如果how_many=0，在列表中没有对象返回，所有对象都可以从iteratorReference中检索。

 

       如果EML可能返回小于how_many项，不是存在的EML对象小于how_many项，就是how_many项超过了服务器的性能限制。例如：一个EML可能返回100个对象，NML通过how_many请求50个返回对象，但是EML只返回了20个对象（包括iteratorReference在内）。

 

       参数iteratorReference是由NMS使用的，来请求更多批次的对象列表。这个参考可以查询有多少对象可以由操作（getLength）返回，和随后NMS可以开始检索或销毁迭代器。如果所有对象都包含在列表中，这个值为COBRA::Object::nil对象。在多数情况下，每个操作都将返回；因此连续调用nexct_n用来检索选定的所有条目。同样，如果EML可能返回小于how_many项，不是存在的EML对象小于how_many项，就是how_many项超过了服务器的性能限制。

 

       在某些情况下，对于EML所包含的元素总数，由迭代器返回也未必是可行的。

              1. EML不得不第一次提取全部需求的数据（本端拷贝）然后计算迭代的元素实例。这提供了特别低的性能。

              2.EML可能包含元素的数量计数，实际数字可能通过不同的迭代时间发生改变。

      

客户端能够确定什么时候所有的数据提供重复的提取数据块直到没有剩余数据了。

 

在EML无法确定长度的情况下，getLength方法应该返回EXCP_CAPACITY_EXCEEDED异常。

 

如果EMS达到实现限制，它将返回EXCP_TOO_MANY_ITERATORS异常。EMS支持最小为10的迭代器。

 

在这个接口中，迭代器有以下操作：

1.              getLength：返回迭代器中元素的总数（不包含已传送的）。例如EML有100个对象，并且10个已经在最初列表中，getLength方法应该返回90，不管有多少对象能否被next_n检索。如果有时EMS不能有效的提供元素的数值，EXCPT_CAPACITY_EXCEEDED异常将被返回。Next_n操作仍可执行。

2.              next_n：最多返回n项条目；它可以少返回。如果还有更多的条目需要返回它将返回TRUE，否则返回FALSE，用于销毁迭代器和释放内存。在一个请求中，EML可以选择返回对象数目的限制，以防止性能上的问题。

3.              destroy：如果客户端决定不读取剩余对象，它可以调用destroy操作来删除迭代对象。