This document describes device groups from programmers point of view and discusses the APIs available for managing device groups on RM, its main components and services.

Overview

Device Groups API provides means for monitoring and managing group types and the groups belonging to them. Using it applications can list existing group types and groups and create new ones. The main components of the API are:

  • com.prosyst.mprm.admin.m2m.groups.GroupType interface – represents a group type. Each group type has ID – which is unique and is used to identify the type – and a user-friendly name. Optionally the group type can provide an icon, which is used for all the groups belonging to this type. Each group belongs to exactly one type. The GroupType interface also provides access to group meta-type, which provides additional info about the allowed actions over groups belonging to the type.

  • com.prosyst.mprm.admin.m2m.groups.GroupMetaType interface – provides a set of properties which give additional information about the allowed actions over groups of the given type – is construction/destruction allowed, which group fields are editable, what are the accepted child group and device types, required and optional parameters for creating a group of this type, etc. Group Meta-Type usage example is provided below:

    import com.prosyst.mprm.admin.m2m.groups.GroupMetaType;
    import com.prosyst.mprm.admin.m2m.groups.GroupType;
     
    ...
     
        GroupType type = ...;
     
        GroupMetaType metaType = type.getMetaType();
     
        boolean isConstructionAllowed = Boolean.TRUE.equals(metaType.getPropertyValue(GroupMetaType.PROPERTY_CONSTRUCTION_ALLOWED));
     
        Object value = meta.getPropertyValue(GroupMetaType.PROPERTY_ALLOWED_DEVICE_TYPES);
     
        if (value instanceof String) {
          String allowedType = (String)value;
          //...
        } else if (value instanceof String[]) {
          String[] allowedTypes = (String[])value;
          //...
        }


  • com.prosyst.mprm.admin.m2m.groups.Group interface – provides methods for reading group fields (name, type, properties, etc.), listing parent and child groups and components contained in the group.

    If a Group instance is editable it would be an instance of EditableGroup also. Below is provided a Group usage example:

    ...
     
      String name = group.getName();
     
      Enumerator  <String, Exception> childGroups = group.listChildGroups(null);
      while (childGroups.hasMoreElements()) {
        String childID = childGroups.nextElement();
        //...
      }

  • com.prosyst.mprm.admin.m2m.groups.EditableGroup interface – represents an editable group. This interface extends com.prosyst.mprm.admin.m2m.groups.Group with methods for editing group fields, adding child groups and components (see the following Group editing example. )

    ...
     
        EditableGroup editable = (EditableGroup)group;
     
        editable.setName("Kitchen");
        editable.setDescription( "Kitchen Devices");
     
        Group whiteGoods = ...
     
        editable.addChildGroup(whiteGoods);

  • com.prosyst.mprm.admin.m2m.groups.GroupAdmin interface – the main entry point to Device Groups API. It contains methods for listing existing group types and groups and for creating new ones. It is registered as service on the back-end (CC, RAS and MS) OSGi frameworks (by packages/osgidm/m2m.groups.ms.jar bundle):

    import org.osgi.framework.BundleActivator;
    import org.osgi.framework.BundleContext;
    import org.osgi.framework.ServiceReference;
     
    import com.prosyst.mprm.admin.m2m.groups.GroupAdmin;
     
    ...
     
      private GroupAdmin groupAdmin;
      private ServiceReference reference;
     
      public void start(BundleContext bc) throws Exception {
        reference = bc.getServiceReference(GroupAdmin.class.getName());
        groupAdmin = (GroupAdmin)bc.getService(reference);
     
        ...
      }


    If you are developing a remote-to-backend application, get the Group Admin service via a Remote Access Client (the service is provided by lib/rac/gdm-rac.jar):

    import java.util.Hashtable;
     
    import com.prosyst.mprm.admin.m2m.groups.GroupAdmin;
    import com.prosyst.mprm.common.ManagementException;
    import com.prosyst.mprm.rac.RemoteAccessClient;
     
    ...
     
       private static RemoteAccessClient rac;
       private static Hashtable< String,  String> credentials;
       private static String userName =  "system";
       private static String URI =  "socket://127.0.0.1:11449" ;
       private static GroupAdmin groupAdmin;
     
    ...
     
        credentials =  new Hashtable< String,  String>();
        credentials.put(RemoteAccessClient.USER_PASSWORD,  "system");
        rac = RemoteAccessClient.connect(URI, userName, credentials,  null);
     
        groupAdmin = (GroupAdmin)rac.getService(GroupAdmin.class.getName());
    ...
During development lib/api/gdm-api.jar can be used to compile applications using Device Groups API.

API Usage

Working with Group Types

GroupAdmin interface provides several methods for working with group types:

  • all currently available group types can be listed using the Enumerator<GroupType, Exception> listGroupTypes() method.

  • GroupType instance can be obtained by its ID using the GroupType getGroupType(String typeID) method.

  • new group types can be created using the GroupType createGroupType(String name, InputStream icon, GroupMetaType metaInfo) or GroupType createGroupType(String id, String name, InputStream icon, GroupMetaType metaInfo). The former method creates new group type with system generated unique ID. The later method creates group type with predefined ID or returns the existing type – if there is already a type with the given ID. Group type IDs are unique in RM. Both methods take optional icon and meta-type arguments.

  • the boolean isGroupTypeUserCreated(String typeID) method can be used to check if group type is user-created.

  • user-created types can be deleted using the void removeGroupType(String typeID) method. This method will throw an error if the type is not user-created.

    ...
     
        GroupType myType = groupAdmin.createGroupType("My Type",  null,  null);
     
        Enumerator&lt;GroupType, Exception&gt; types = groupAdmin.listGroupTypes();
         while (types.hasMoreElements()) {
          GroupType type = types.nextElement();
           //...
        }

Managing Groups

Listing Groups

GroupAdmin interface provides several methods for listing groups:

  • Enumerator<String, Exception> listGroupsByType(String typeID) returns enumerator with the IDs of all available groups of given type.

  • Enumerator<String, Exception> listGroups(String ldapFilter) returns all groups that match given LDAP filter. If the filter is omitted (i.e. is null) all available groups will be returned. The properties which can be used in the filter are defined in com.prosyst.mprm.admin.m2m.groups.GroupFilterPropertyConstants.

  • Group findGroupByID(String groupID) can be used to get a group with the given ID. If no group has the given ID – null is returned. Group IDs are unique in RM.

    ...
     
        Enumerator&lt;String, Exception&gt; ids = groupAdmin.listGroups( "(" + GroupFilterPropertyConstants.GROUP_NAME +  "=My Group)");
     
         while (ids.hasMoreElements()) {
          Group group = groupAdmin.findGroupByID(ids.nextElement());
           //...
        }

Creating New Groups

For creating new groups Group createGroup(GroupType type, String name, Map<String, String> properties) method should be used. The type under which the new group will be created must be specified as well as a name for the new group. Optionally creation properties may be needed by some group types. User-created types have no required creation properties. The Group Admin will create a new group with unique ID and return a Group interface instance. If the group is editable this instance can be cast to EditableGroup. Groups of user-created types are always editable.

...
 
    EditableGroup group = (EditableGroup)groupAdmin.createGroup(myType, "My Group",  null);
    group.addChildGroup(childGroup);

Deleting Groups

Groups are deleted using the void removeGroup(GroupType groupType, String groupID) method.

Root Group

There is a special root group – accessible through Group getRootGroup() method - which will have as child groups all other groups that are not assigned under any other parent group. Groups will be automatically removed from this group when they are assigned to some other parent group. The root group is not editable.

Listening for Group Events

Using the Group Admin void addGroupAdminListener(GroupAdminListener listener) method applications can register for receiving group added/removed and group type added/removed events. Listeners registered through this method are removed with void removeGroupAdminListener(GroupAdminListener listener) method.

...
   GroupAdminListener listener = new GroupAdminListener() {
 
      public void handleEvent(GroupTypeEvent event) {
        System.out.println(event);
      }
 
      public void handle(GroupEvent event) {
        System.out.println(event);
      }
    };
 
    groupAdmin.addGroupAdminListener(listener);
 
...
    
    groupAdmin.removeGroupAdminListener(listener);

To listen for changes in particular group – field changes, adding/removing child groups or components, applications have to register listener in the corresponding Group using void addGroupListener(GroupChangeListener listener) method. Listeners registered in this way are removed using void removeGroupListener(GroupChangeListener listener) method.


...
  private Group myGroup;
 
...
 
    GroupChangeListener listener = new GroupChangeListener() {
 
      public void handleGroupPropertEvent(GroupPropertyEvent event) {
        System.out.println(event);
      }
 
      public void handleGroupComponentEvent(GroupComponentEvent event) {
        System.out.println(event);
      }
 
      public void handleGroupChildEvent(GroupChildEvent event) {
        System.out.println(event);
      }
    };
    
    myGroup.addGroupListener(listener);
 
...
    
    myGroup.removeGroupListener(listener);