DataManager  - AS3 ADEP Data Services

控制与服务器交互的类的实例。

指示是否自动提交对本地缓存进行的更改。已提交的更改将立即发送到远程服务。

对于 DataService 实例，即用于服务器端 Data Management Service 的数据管理器，默认值为 true。

对于 RPCDataManager 实例，即向 RPC 服务组件（如 RemoteObject、HTTPMultiService 和 WebService）提供客户端数据管理功能的数据管理器，默认值为 false。

指示此服务是否应为需要连接的任何操作尝试连接。如果该服务断开连接并且 autoConnect 设置为 true，则 fill()、getItem() 和 count() 等操作将尝试连接。使用此属性可以控制偶尔连接的应用程序行为。

默认值为 true。

如果设置为 false，则当将更改从远程目标推送到客户端时不会立即应用。相反，mergeRequired 属性设置为 true。

可以注册事件处理程序来侦听此属性的更改事件，以在需要应用合并时获得通知。

若要合并更改，可调用 merge() 方法，会应用所有更改。

如果存在任何需要合并的更改，则不能提交未提交的更改。

如果启用分页，在调用 merge() 之前将缓存非本地项的所有请求。调用 merge() 后将处理缓存的请求。

默认值为 true。

可以将数据和更改的本地缓存保存到磁盘中。如果 autoSaveCache 属性为 true，每次进行更改或返回远程请求时，数据都会保存到磁盘中。如果由于磁盘已满或写入权限被拒绝而在保存数据时遇到问题，则调度 FaultEvent 或引发 Fault。

将此值设置为 false（默认值），则不会将任何数据或更改保存到磁盘。要强制将当前数据和更改保存到磁盘中，可使用 saveCache() 方法。

默认值为 false。

相关 API 元素

如果为 true，fill()、createItem() 和 getItem() 请求将返回负责侦听对远程目标中的项进行的更新的项。如果更改此属性值，则只影响将来对这些方法的调用，而不会影响现有集合或项。

另请注意，如果将使用 autoSyncEnabled 检索到的集合和未使用 autoSyncEnabled 填充的组合放在一起，则同时出现在这两种集合中的项仍会接收更新事件。

默认值为 true。

提供对此服务的缓存标识的访问。在执行任何要求与本地磁盘中存储的数据进行交互的操作之前，必须先设置缓存标识。如果未设置缓存标识，则认为并非所有缓存方法和属性都一致，而且在执行任何需要本地磁盘数据的操作期间会引发 DataServiceError。此属性为本地存储的数据提供唯一“会话”标识。开发人员必须将此属性设置为应用程序的唯一值。

null 值或空字符串表示未进行设置。如果已设置 cacheID，fill() 和 getItem() 等方法提出的数据请求将尝试首先访问磁盘上的本地数据。如果未设置 cacheID，将不会尝试访问任何本地数据。

指示是否存在未提交的更改以及是否应该调用 commit() 方法。如果此属性发生更改，则会调度事件。可以在应用程序中使用此属性来提供可视反馈。

此属性可用作数据绑定的源。修改此属性后，将调度 propertyChange 事件。

提供对当前实现的访问，此实现正用于检测推送到 DataManager 实例的远程操作的冲突。

包含 Conflicts 对象，即 Conflict 实例的 ArrayList。

必须解决冲突才能调用 commit() 方法。要解决冲突，可以遍历冲突并单独解决每个冲突，或对此属性调用 acceptAllClient() 方法或 acceptAllServer() 方法。

此属性可用作数据绑定的源。修改此属性后，将调度 propertyChange 事件。

指示 DataService 是否已连接到远程目标。

此属性可用作数据绑定的源。修改此属性后，将调度 propertyChange 事件。

包含一个 mx.data.DataStore 类型的对象。DataStore 实例为一个或多个 DataManager 实例（相互之间可以进行引用）管理一组传入和传出更改。提交 DataStore 时，会提交每个使用该 DataStore 的 DataManager 的所有挂起更改。

默认情况下，如果 DataManager 实例和其它 DataManager 实例管理了关联属性并共享同一组通道，则它们将共享同一个 DataStore。如果您正在共享 DataStore，则对一个 DataManager 的 commit 调用将提交对使用该数据存储的所有 DataManager 的更改。如果未提交的批次中的更改之间存在相关性，这会保留操作顺序。

此属性可用作数据绑定的源。修改此属性后，将调度 propertyChange 事件。

默认情况下，当您对托管填充集合调用 removeItemAt() 方法时，它会向服务器发出一个删除项调用以物理删除该项。这允许您使用以同样的方式使用托管集合和非托管集合的代码。但在其它情况下，您可能希望将项从客户端的集合中移除，而不是将其从服务器中删除。在这种情况下，请在调用 removeItemAt() 方法前将此标志设置为 false。

请注意，这不会影响关联的集合。只会影响用于 fill() 方法的集合。

默认值为 true。

指示是否应为使用 SQL 脱机适配器的 AIR 客户端加密脱机存储。

对于基于浏览器的 Flex 客户端，无法加密脱机数据。

此标志确定当应用程序断开连接时是否对本地存储进行查询。默认情况下，当将脱机适配器配置为支持动态查询执行时，调用 fill() 方法不会在应用程序断开连接时查询本地存储。如果 fallBackToLocalFill 设置为 true，则即使应用程序断开连接也查询本地存储。

此属性可用作数据绑定的源。修改此属性后，将调度 propertyChange 事件。

关联选择性地列出关联实例属性上的属性更改事件。您可以在与 hierarchical-events 配置属性关联时对此进行设置。如果不设置 hierarchical-events 属性，特定目标的关联将使用此属性确定默认值。

默认值为 false。对于树（而不是循环图形）中的对象，为简便起见，您可能希望为目标将此项设置为 true。例如，如果使用项呈示器中属性的属性，则为该关联属性将此项设置为 true 会导致网格在属性的这些属性发生更改时刷新。系统有能力避免发送递归事件或创建大型事件链，例如 parent.child[0].child[1].child[3]。

默认值为 false。

指示是否忽略对托管集合所做的更改，而不针对提交与服务器通信。

默认值为 false。

要调整应用程序的速度，如果您对此 DataManager 所管理的、其它项的关联属性中的项进行了少量的填充或引用，请将此属性设置为 false。

指示是否初始化与此 DataManager 实例相关联的元数据。

此属性可用作数据绑定的源。修改此属性后，将调度 propertyChange 事件。

为每个 DataManager 实例提供对 ManualSyncConfiguration 实例的访问。使用 ManualSyncConfiguration 类，可以订阅由其它客户端进行的更改或服务器上的更改，还可以控制如何将更改发布到使用此接口订阅的其它客户端。

确定 DataManager 实例可以每秒收到的最大消息数。理解此值的服务器将使用此值确定向 DataManager 发送消息的速度。

默认值为 0，表示 DataManager 没有消息速度首选项。请注意，应在 DataManager 订阅之前设置此属性，在订阅后所做的任何更改直到 DatManager 取消订阅并重新订阅后才会生效。

默认值为 0。

指示是否存在必须合并的挂起更改。

此属性可用作数据绑定的源。修改此属性后，将调度 propertyChange 事件。

返回一个 mx.data.DataServiceOfflineAdapter 类型的对象。脱机适配器控制针对如何在本地存储 (SQLLite/LSO) 上持久保存对象的实现。

提供对所有集合的当前页面大小设置的访问。

指示是否将远程目标配置为允许分页请求。

DataManager 实例发送的消息的默认消息优先级。有效值为 0 到 9（0 表示最低优先级），值 -1 表示 DataManager 实例未设置优先级。请注意，如果已为消息定义了优先级，则所定义的优先级优先于此优先级。

提供对操作的请求超时（以秒为单位）的访问。如果值小于 0 或等于 0，则可阻止请求超时的发生。如果当前操作由于达到了 requestTimeout 限制而超时，则会为该操作调度 fault 事件，表明请求已超时。请注意，有时虽然操作发生超时，服务器实际上仍收到了该操作。这就使得客户端状态与服务器不同步。

如果属性为 true，则在 fill 操作完成后，会发送 RESET 事件。如果此属性为 false，对 fill 结果返回的每个项仅发送增量 ADD/REMOVE 事件。设置此属性会影响您发起的所有填充操作。在开始填充后进行更改不会影响未完成的填充行为。

默认值为 true。

控制已断开连接的 DataManager 实例尝试重新订阅目标的次数。默认值 -1 表示在客户端能够重新连接前不断进行重新订阅。

默认值为 -1。

控制重新订阅尝试之间的延迟（以毫秒为单位）。默认值为 5000，意味着每 5 秒尝试重新订阅一次。

默认值为 5000。

指示是否存在尚未保存至本地缓存的更改，以及是否应该调用 saveCache() 方法。commitRequired 应该返回 true 时，此方法可能返回 false，指示更改已保存至本地缓存，但未提交到服务器。

此属性可用作数据绑定的源。修改此属性后，将调度 propertyChange 事件。

指示 DataManager 实例是否已订阅到远程目标。

此属性可用作数据绑定的源。修改此属性后，将调度 propertyChange 事件。

如果您要在访问延迟访存的数据或未分页的数据时禁止项挂起错误，请将此属性设置为 false。将为 ArrayCollection 中的属性值或 getItemAt() 调用返回 null，而不是引发错误。

对于尚未从服务器中访存其大小的列表，size() 返回 0 个元素。当从服务器返回该元素时，将调度相应的 PropertyChangeEvent 和 CollectionEvent 事件。

使用指定目标构造 DataService 的实例。目标必须是对在 services-config.xml 文件中配置的目标的引用。

如果尚未初始化此数据管理器，则使故障排队。

清除以前调用 saveCache() 方法或将 autoSaveCache 方法设置为 true 时存储到磁盘中的所有数据

参数

清除由从本地存储传递的描述符指定的数据。

参数

提交当前由与此 DataManager 实例关联的 DataStore 实例管理的所有集合的挂起更改。调用此方法等同于调用 dataStore.commit() 方法。

如果 autoCommit 属性为 true，则不会使用事务，并且不需要调用此方法。要使用事务，请将 autoCommit 属性设置为 false，然后直接调用此方法以提交一批更改。

通常，只需调用不包含参数的 commit()，即可提交所有挂起的更改。可以提供可选的自变量来提交挂起更改的子集。必须首先解决所有未解决的冲突，然后才能提交对 DataStore 中的任何项所做的更改。

如果组装器配置为将 use-transactions 设置为 true，则会自动提交所有更改。如果任一操作失败，则不会应用该批次中的任何操作。如果将 use-transactions 设置为 false，则单独提交各个操作，直到发生失败（此时处理将停止）为止。将应用出错之前发生的任何更改，但不会应用出错之后发生的任何更改。如果在处理某个批次时出现错误，则将更改放回到未提交的队列中。如果要删除导致错误的更改，则需要调用 revertChanges。

默认情况下，commit 方法将提交已为此 DataStore 创建、修改和删除的所有项的所有挂起更改。如果要提交这些更改的子集，则可以指定托管 ArrayCollection 实例和/或托管项的组合，以定义要在该批次中包含的更改子集。对于指定的各个数组集合，无论是更改其中项的成员身份或顺序，还是更改其中的项，都会提交相应的更改。您还可以指定各个托管项的列表，以便只提交对这些项进行的更改。如果在 itemsOrCollections 参数中指定了任何不是托管集合或托管项的对象，则会引发 DataServiceError。

如果使用 itemsOrCollections 参数，并且您的项具有引用其它项的关联属性，则可以使用 cascadeCommit 参数控制是否也在该批次中包含对关联项进行的更改。例如，如果在项参数中指定了一个 Group 项，并且 Group 实例具有一个在 cascadeCommit 为 true 时引用 Person 实例列表的成员属性，则对任何 Person 实例的更改也将包含在提交的更改集中。如果 cascadeCommit 为 false，则只包含对 Group 进行的更改。使用 cascadeCommit=true 可确保该批次中包含所有相关更改。

参数

指示是否存在此特定对象的挂起更改。允许在 UI 上启用粒度。（请参阅针对通知的可绑定属性的 commitRequired。）

参数

强制此服务尝试连接到远程目标。此方法可与 autoConnect 属性和 disconnect() 方法一起使用来控制连接状态。

调用远程目标上的计数方法。调用的计数方法基于关联的 <count-method> 标记和传递的参数。例如，如果执行以下 count("firstName", "Bob" ) 调用，并且存在 <count-method> 标记或在关联目标下的 services-config.xml 中引用这些标记：

            <count-method>
                <name>getCount</name>
                <params>java.lang.String,java.lang.String</params>
                <security-run-as name="freddie" password="nightmare" />
            </count-method>
     
            <count-method>
                <name>getCount</name>
                <security-constraint ref="sample-users" />
            </count-method>
      

参数

相关 API 元素

请求在远程存储中创建指定项。如果出现错误，则调度 DataConflictEvent 事件。

参数

请求从远程存储中删除指定项。如果出现错误，则调度 DataConflictEvent 事件。

参数

断开 DataManager 实例的网络连接。此方法不会等待未完成的网络操作完成。

使用提供的名称和自变量执行查询。通常将此方法与 RPCDataManager 实例一起使用，其中查询具有特定名称。只要 fill-method 的第一个参数是字符串值，还可以将此方法与使用更常用的 fill-method 方法定义的查询一起使用。queryName 用作第一个 fill 参数。

请注意，在结束此方法返回的对象时，应为集合结果调用 releaseCollection() 方法或为单一值项结果调用 releaseItem。或者，您可以通过调用 release() 方法释放从该 DataManager 实例中检索到的所有托管引用。

调用 refreshCollection() 方法刷新此方法返回的所有集合的内容。

参数

根据目标的关联 fill 方法填充指定的 ListCollectionView（集合）实例。例如，对于使用 Hibernate 组装器的 LiveCycle Data Services 目标，fill() 方法的第一个参数为要填充的集合，第二个参数为要执行的 Hibernate 查询，其它所有参数都是 Hibernate 查询参数。对于模型驱动的开发，此相同格式应用于在服务包装器类中使用的 fill()。

下例显示了使用 Hibernate 组装器的目标的 fill() 方法。组装器具有名为 getByDescription 的查询及其名为 description 的查询参数。

     ProductService.fill(ac, "getByDescription", description);
     

对于使用 fill-method 方法（在其中声明目标配置中 XML 元素中的 fill 方法）的 LiveCycle Data Services 目标，如果在目标配置中有以下 <fill-method> 元素：

            <fill-method>
                <name>loadPersons</name>
                <params>java.lang.String,java.lang.String</params>
            </fill-method>
     
            <fill-method>
                <name>loadPersons</name>
                <security-constraint ref="sample-users" />
            </fill-method>
      

参数

根据目标的关联 fill 方法填充指定的 ListCollectionView（集合）实例。仅会在每个对象上填充属性的一个子集，由 propertySpecifier 参数指定。

参数

执行一个返回单个项的查询。

参数

返回本地存储中的 ArrayCollection 或单个托管对象。调用此方法不会更新上次访问时间。

参数

使用 CacheDataDescriptor 实例填充指定的 ListCollectionView（集合）实例。如果未指定任何参数，则返回此服务下缓存的数据的所有关联的 CacheDataDescriptor 实例。

参数

使用之前在应用程序中使用的所有缓存标识符来填充指定的 ListCollectionView（集合）实例。

参数

对与指定标识匹配的项发出异步请求。如果您提供了一个 defaultValue，但该项不存在，则将创建该项，而不是使用 defaultValue 中的信息。此方法返回 ItemReference 实例。如果从 getItem() 方法调用收到有效实例，则必须调用 releaseItem() 方法来释放该项的实例。如果保留 ItemReference 实例，则应针对该引用调用 releaseItem() 方法以确保释放的是正确的引用，以防您的客户端已对相同项执行了多次 getItem () 方法调用。如果不保留 ItemReference 实例，您可以使项自身来针对 DataManager 调用 releaseItem() 方法。

参数

使用给定的标识查找所提供的项。如果此客户端上已托管该项，则返回托管实例。否则，返回 null。与调用 getItem 方法不同，此调用不会向服务器提出请求，也不向此项中添加其它引用。

参数

返回指定集合的页面信息。

参数

返回消息缓存中针对指定项的挂起操作。使用此方法为用户提供有关已对项进行了哪些类型的更改（如果有）的可视反馈。

参数

强制初始化 DataStore。

如果传递的集合由此服务管理，则返回 true。如果集合由此服务托管，则将该集合传递给 releaseCollection() 以将其从管理中释放会非常安全。

参数

如果传递的集合要使用分页功能，则返回 true。如果该集合由此服务分页，则将集合传递给 releaseItemsFromCollection() 以从管理中释放集合中的各个项会非常安全。

参数

如果将提供的项范围全部页入，则返回 true。否则，返回 false。

参数

根据关联的 <fill-method> 元素基于本地存储上的数据填充指定的 ListCollectionView。将调用 offlineAdapter.executeOfflineQuery() API 来查询数据，并且即使连接了应用程序也不会查询远程目标。理想的使用方法是在客户端上同步数据并对客户端进行本地查询。

参数

将所有挂起更新合并到托管对象集中。合并更改过程将检测冲突并处理所有挂起的项请求。这将合并共享此 DataStore 实例的任何其它 DataManager 实例的所有消息。

刷新由此 DataManager 实例管理的所有数据。对服务器进行填充、获取项请求和页面请求，以重新访存所有托管项。调用 DataStore.refresh() 方法也可刷新惰性为 true 关联的所有关联项。

刷新先前使用 fill 方法填充或作为托管关联进行管理的集合。此方法向服务器提出请求，使用先前与此集合一起使用的 fill 参数或通过访存父代中的属性来访存集合中任何常驻项的新版本。如果发现任何更改，会将它们以增量方式合并到集合中。

参数

释放 DataManager 实例的所有托管集合和项。

参数

相关 API 元素

使指定集合中的所有项脱离此 DataManager 实例的管理。如果项存在于多个集合中，则创建该项的副本。会释放对仅存在于此集合中的项所做的任何未提交更改，包括删除、创建和更新。

参数

使指定的项脱离此 DataManager 实例的管理。如果保留到 ItemReference 实例，那么当您可能已执行多个 getItem() 调用，而这些调用从客户 应用程序的不同部分检索相同的项时，应针对 ItemReference 实例调用 releaseItem() 方法，以确保释放正确的引用。

此调用释放所有关联的资源，包括嵌套属性。指定项不再从远程目标接收更新。此外，如果存在对此项进行的任何未提交的更改，且该项没有出现在任何其它集合中，这些更改也会被释放。如果指定项存在于多个集合中，除非将 allowCopy 参数设置为 false，否则返回的值将是原始项的副本。

参数

释放集合中的一系列项。在大型集合中分页时，您可能希望释放被集合中的项占用的资源并停止订阅这些项的更新。指定希望释放的第一个项的 startIndex 和要释放的项数。如果尚未对该位置上的项进行分页，则跳过该索引。

参数

释放单值关联的值。如果该值未页入，则返回 false。如果该值页入，则释放该引用并返回 true。如果这是对特定项目的最后一个引用，则下次尝试访问该项目时将导致出现 ItemPendingError，并再次访存该值。

参数

还原对指定项进行的所有未提交的更改。或者，如果没有提供任何项，则还原所有未提交的更改。如果还原创建操作，则会删除此项。如果还原删除操作，则会重新添加已删除的项。还原更新将复原开始更改项之前设置的项原始属性。调用此方法等同于调用 dataStore.revertChanges() 方法。

使用此方法的一种情况是在出现错误后。在这种情况下，任何失败的更改都将回置到未提交的更改列表中。此时，您可以修改这些更改以解决问题，或使用此方法进行还原以阻止重新提交这些更改。

如果提供了一个项，但该项不包含任何更改，则此方法返回 false。如果没有提供任何项且没有进行任何更改，则此方法将返回 false。否则，将返回 true。

参数

还原指定集合中包含的、应由此 DataManager 实例管理的所有项的更改。

参数

此方法保存当前状态的 DataManager 实例缓存。缓存包括内存项和对项所做的尚未发送到远程目标的更改。

参数

相关 API 元素

         var customerService:DataService = new DataService("customers");
         var customers:ArrayCollection = new ArrayCollection();
         customerService.fill(customers);
         // ...
         var customer:Customer = Customer(customers[0]);
         customer.priority = "top";
         customerService.saveCache();
         // now all of the changes and items in the customers collection
         // will be persisted locally
      

指示是否存在对此特定对象所做的未保存至本地缓存的暂挂更改。comitRequiredOn 应该返回 true 时，此方法可能返回 false，指示更改已保存至本地缓存，但未提交到服务器。

参数

获取之前在此数据服务（数据管理器）上执行的所有填充的已更改项。

允许所有本地数据的同步的简便方法：针对每个数据服务（数据管理器）调用 synchronizeAllFills()，以便仅当所有单个 synchronizeAllFills() 调用完成后，才完成最终结果标记。

参数

获取上一次调用 fill 或 synchronizeFill 后在服务器上更改的已更改项。这包含已创建的项、已更新的项和已删除的项。如果之前没有执行过填充，这等效于第一次执行填充。

参数

触发指定项目的更新。如果使用托管实例调用此方法，则它将提交已对该项所做的任何更改，并返回一个可以用于跟踪这些更改的标记。如果不存在对该项目的挂起更改，则返回一个 null 标记。如果您使用该实例的另一个副本调用此方法，则它会将更改数组中的所有已更改属性复制到记录任何更改的托管实例，然后提交这些更改。如果 autoCommit 设置为 true，则会立即提交对此项的更改。如果设置为 false，则排队等候，直到调用 commit() 方法后再提交所做的更改。

参数

如果在挂起的本地更改和其它客户端提交的更改之间检测到冲突，或者此客户端提交的更改与远程目标中的更改发生冲突，则调度 DataConflictEvent.CONFLICT 事件。每个 DataService 仅为此特定目标的项发送冲突事件。如果您需要同时为一组相关目标处理冲突，请使用 DataService 上的冲突事件。

事件对象的属性有下列值：

当由于错误而导致服务调用失败时，将调度 DataManagerFaultEvent.FAULT 事件。例如，如果 fill() 方法调用失败，则该调用会调度此事件。对于在提交结果中生成错误的各个项，也会获得此事件。在这种情况下，DataServiceFaultEvent 将包含 commit 返回的标记，但是错误中的项和错误消息字符串特定于导致该错误的项。

事件对象的属性有下列值：

当远程目标推送数据操作的通知时，将调度 MessageEvent.MESSAGE 事件。例如，在远程目标上更新数据时，会将更新操作发送给所有正在侦听的客户端，然后在此 DataService 上将此操作转换为 message 事件。

此常量的值为 "message"。

事件对象的属性有下列值：

此服务的属性发生更改时，将调度 PropertyChangeEvent.PROPERTY_CHANGE 事件。下列属性会出现这种情况：

• commitRequired
• mergeRequired
• connected

事件对象的属性有下列值：

当服务调用成功返回时，将调度 ResultEvent.RESULT 事件。例如，如果 fill() 调用成功，则该调用会调度此事件。

事件对象的属性有下列值：