Handles are identifiers of addressable items used with IAP/MQ topics. Most of these handles must be created by the tool that creates the item, such as an IAP group object. However, any IAP client tool can create such an item, and all handles must be unique.  

The CMS allocates most handles, including handles that do not include the “.” (period) character. Most other tools do not need to create handles. They rely on CMS services to do so, and work with objects and their handles as created by the CMS.

However, tools can create unique handles based on knowledge acquired from observation of the IAP/MQ feedback channel. Because race conditions between competing tools can occur, IAP/MQ recommends the following allocation policy:

• The CMS is the prime citizen within an IAP/MQ system. As a prime citizen, the CMS allocates plain handles based on its own allocation algorithm. A plain handle does not include a period character. The CMS may also implement its own handle space as recommended for other tools.
  
  
• Other tools in need of a unique handle, allocate handles within the tool’s own handle space, followed by a “.” (period) character, and then followed by a unique handle within that space.  For example, a tool can allocate handles in the form of myTool.x12, where “myTool” is the tool’s handle space identifier and “x12” is the handle allocated by the tool, unique within the "myTool" space.
  
  
• Tools can acquire their unique handle space identifier in different ways:
  
  
  • Tools might be able to rely on a quasi-unique tool name for use with a deterministic system. The hypothetical “WM2000” app by Acme Inc, for example, could rely on acme-wm2000 for a quasi-unique handle space identifier. This tool could create handles as acme-wm2000.d-0 or acme-wm2000.g-1, for example.
    
    
  • Other tools draw on a standard universally unique identifier (UUID) for more reliable allocation of a quasi-unique handle space identifier. For example, a version 4 UUID of a554dc70-f705-4e15-9598-ccf475a8a5e7 could be drawn as the tool’s quasi-unique handle space identifier. This tool could create handles as a554dc70-f705-4e15-9598-ccf475a8a5e7.a, a554dc70-f705-4e15-9598-ccf475a8a5e7.b, for example.
    
    
  • Tools may also engage the IAP/MQ Handle Allocation Service to obtain a unique handle space identifier at runtime. This identifier is guaranteed to be unique within a given segment, is short and human-readable, such as “0”, “1”, or “k2”. Such a tool could create handles in the form of 0.a or 0.b, for example.

Handle Allocation Service

To allocate a unique handle space identifier, an IAP client publishes an IAP/MQ handle request object to a well-defined topic. The edge server responds by publishing an IAP/MQ handle response object at another well-defined topic. The handle allocation service returns a unique handle. For efficiency, callers are expected to use the returned handle for their handle space identifier, then implement a simple handle allocation algorithm to create handles unique within that handle space.

The edge server provides a handle space identifier that is unique within all handles allocated in this manner. Handles are never reused and are unique within the segment, not just within the group objects or device objects.

Handles returned from this service are short and human-readable. One implementation could, for example, maintain a simple integer counter and return new handles as the base-36 encoding of the counter value. Other implementations are possible as long as the handle is unique and meets the IAP/MQ handle character set described under Handle in the Device Syntax table.

Deprovisioning or provisioning a segment controller can reset the handle allocator. Implementations of the handle allocation service can also support allocating handles that persist over segment deprovisioning and segment provisioning procedures, if the system that the handle allocation service serves requires persistent handles.

When persistent handles are allocated, the handle allocation service is responsible for creating handles such that no information about the segment or any of its configuration aspects can be obtained from a handle.  For example, the segment identifier, its owner, or location should not be included with a persistent handle so that a segment that has been provisioned for one deployment, then deprovisioned, and later provisioned for another deployment, cannot acquire knowledge about the previous deployment.

Handle Request

The handle request topic is:

The Handle Request Object, which is published to the handle request topic, has the following property:

Handle Response

The handle response topic is:

The Handle Response Object, which is published to the handle response topic, has these properties:

Example

The following is a JSON formatted handle response object:

The JSON response above would be seen the on the 20th request for a handle from this edge server.