com.ibm.soa.parlayx21.group_mgmt
Interface GroupManagement

All Superinterfaces:
java.rmi.Remote
All Known Subinterfaces:
GroupManagement_RI
All Known Implementing Classes:
GroupManagementBindingStub, GroupManagementProxy

public interface GroupManagement
extends java.rmi.Remote

This interface provides the administration interface for creating, deleting, querying and managing access rights for groups. The format of the group name is specified in the Detailed Service Description (see clause 4).


Method Summary
 java.net.URI createGroup(java.lang.String name, java.lang.String domain, boolean autoName)
          Create a new group.
 void deleteGroup(java.net.URI group)
          Delete a group.
 AccessPermissions queryAccess(java.net.URI group, java.lang.String requester)
          Query the access permissions for a requester on a group.
 java.net.URI[] queryGroups(java.lang.String searchDomain, boolean hierarchy)
          Group information can be retrieved from the network, with two types of search, one that retrieves groups only from a single sub-domain and one that returns groups from the sub-domain and its sub-domains.
 void setAccess(java.net.URI group, java.lang.String requester, boolean adminPermission, boolean addPermission, boolean deletePermission, boolean queryPermission)
          Access to manage the elements within a group may be provided independently from the access to manage the group itself.
 

Method Detail

createGroup

java.net.URI createGroup(java.lang.String name,
                         java.lang.String domain,
                         boolean autoName)
                         throws java.rmi.RemoteException,
                                PolicyException,
                                ServiceException

Create a new group. The requester provides the name for the group and the domain segment in which the group is to be stored. A domain segment is used, since the full domain will consist of the domain segment provided by the requester (for example, 'sales.mycompany') plus a period separator ('.') per RFC 2396 [3] and the domain segment provided by the Service Provider (for example, 'serviceprovider.com').

To avoid name conflicts, since group URIs must be unique, an automatic naming capability is provided which will append a suffix to the name provided if the name is already used within the domain. If the AutoName is set to 'true' and the fully qualified name is not unique, then the name will have a suffix added and the unique name will be provided in the result. For example, if the group 'sales@mycompany.serviceprovider.com' was already defined, a suffix would be added and the result could be 'sales1@mycompany.serviceprovider.com'. If the AutoName is set to 'false', then a PolicyException is thrown if the group URI is not unique.

Referenced faults

ServiceException from ES 202 391-1 [2]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.

PolicyException from ES 202 391-1 [2]:
  * POL0001: Policy error.
  * POL0212: Group name too long.
  * POL0213: Group already exists.

Parameters:
domain - xsd:string Domain segment to be contained within the domain provided by the Service Provider. May be hierarchical using period separators (see RFC 2396 [3])
autoName - xsd:boolean If false, name must be unique or it will not be created. If true, a suffix will be added to the name if it is not unique
Returns:
xsd:string Name of group to be included in group name
Throws:
java.rmi.RemoteException
PolicyException
ServiceException

deleteGroup

void deleteGroup(java.net.URI group)
                 throws java.rmi.RemoteException,
                        PolicyException,
                        ServiceException

Delete a group.

Referenced faults

ServiceException from ES 202 391-1 [2]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.

PolicyException from ES 202 391-1 [2]:
  * POL0001: Policy error.

Parameters:
group - xsd:anyURI Name of group to delete
Throws:
java.rmi.RemoteException
PolicyException
ServiceException

queryGroups

java.net.URI[] queryGroups(java.lang.String searchDomain,
                           boolean hierarchy)
                           throws java.rmi.RemoteException,
                                  PolicyException,
                                  ServiceException

Group information can be retrieved from the network, with two types of search, one that retrieves groups only from a single sub-domain and one that returns groups from the sub-domain and its sub-domains.

An example demonstrates the two search types. The following example data is used:
  * Dept123@region1.sales.mycompany.serviceprovider.com
  * Dept245@region2.sales.mycompany.serviceprovider.com
  * Dept348@sales.mycompany.serviceprovider.com
  * Dept367@sales.mycompany.serviceprovider.com
  * Dept875@finance.mycompany.serviceprovider.com

For a search using the search domain 'sales.mycompany', with the hierarchy set to 'false', the result will contain:
  * Dept348@sales.mycompany.serviceprovider.com
  * Dept367@sales.mycompany.serviceprovider.com

If the same search domain 'sales.mycompany' is used, but the hierarchy set to 'true', the result will contain:
  * Dept123@region1.sales.mycompany.serviceprovider.com
  * Dept245@region2.sales.mycompany.serviceprovider.com
  * Dept348@sales.mycompany.serviceprovider.com
  * Dept367@sales.mycompany.serviceprovider.com

Referenced faults

ServiceException from ES 202 391-1 [2]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.

PolicyException from ES 202 391-1 [2]:
  * POL0001: Policy error.

Parameters:
searchDomain - xsd:string Sub-domain to retrieve groups from
hierarchy - xsd:boolean Follow hierarchy under search name
Returns:
result xsd:anyURI [0..unbounded] Array of items matching search criteria
Throws:
java.rmi.RemoteException
PolicyException
ServiceException

setAccess

void setAccess(java.net.URI group,
               java.lang.String requester,
               boolean adminPermission,
               boolean addPermission,
               boolean deletePermission,
               boolean queryPermission)
               throws java.rmi.RemoteException,
                      PolicyException,
                      ServiceException

Access to manage the elements within a group may be provided independently from the access to manage the group itself. This operation enables the group administrator to specify the requester and the operations the requester is permitted to perform through the Group interface.

The access rights are absolute, if a requester has 'query' access currently and 'add' access is to be added, then the request requires both 'add' and 'query' rights to be set to 'true'. Likewise, any right that is set to 'false' will be revoked.

Referenced faults

ServiceException from ES 202 391-1 [2]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.

PolicyException from ES 202 391-1 [2]:
  * POL0001: Policy error.

Parameters:
group - xsd:anyURI Group to grant access to
requester - xsd:string Requester to grant access to
adminPermission - xsd:Boolean Permission to manage group
addPermission - xsd:Boolean Permission to add members to the group
deletePermission - xsd:Boolean Permission to delete members from the group
queryPermission - xsd:Boolean Permission to query members in the group
Throws:
java.rmi.RemoteException
PolicyException
ServiceException

queryAccess

AccessPermissions queryAccess(java.net.URI group,
                              java.lang.String requester)
                              throws java.rmi.RemoteException,
                                     PolicyException,
                                     ServiceException

Query the access permissions for a requester on a group.

Referenced faults

ServiceException from ES 202 391-1 [2]:
  * SVC0001: Service error.
  * SVC0002: Invalid input value.

PolicyException from ES 202 391-1 [2]:
  * POL0001: Policy error.

Parameters:
group - xsd:anyURI Group to which permissions are to be granted
requester - xsd:string Requester to retrieve access permissions for
Returns:
permissionsresult AccessPermissions List of permissions that a requester has
Throws:
java.rmi.RemoteException
PolicyException
ServiceException


Copyright © 2003 IBM Corp. All Rights Reserved.