es.upv.dsic.gti_ia.organization
Class OMSProxy

java.lang.Object
  es.upv.dsic.gti_ia.organization.THOMASProxy
      es.upv.dsic.gti_ia.organization.OMSProxy

public class OMSProxy
extends THOMASProxy

This class gives us the support to accede to the services of the OMS. The OMS provides a group of services for registering or deregistering structural components, specific roles, norms and units. It also offers services for reporting on these components.

Author:

Joan Bellver Faus

Constructor Summary

OMSProxy(BaseAgent agent)
This class gives us the support to accede to the services of the OMS, Checked that the data contained in the file configuration/Settings.xml, the URL ServiceDescriptionLocation is not empty and is the correct path.

OMSProxy(BaseAgent agent, String OMSServiceDescriptionLocation)
This class gives us the support to access to the services of the OMS

OMSProxy(CProcessor myProcessor)

OMSProxy(CProcessor agent, String OMSServiceDescriptionLocation)

Method Summary

String	acquireRole(String RoleID, String UnitID) Service used for acquiring a role inside a specific unit.
String	allocateRole(String RoleID, String UnitID, String TargetAgentID) Forces an agent to acquire a specific role
ACLMessage	buildOrganizationalMessage(String OrganizationID) Builds a new organizational message with the appropriate receivers according to the type of unit and position of the role that the agent is performing
String	deallocateRole(String RoleID, String UnitID, String TargetAgentID) Forces an agent to leave a specific role
String	deregisterRole(String RoleID, String UnitID) Removes a specific role from a unit.
String	deregisterUnit(String UnitID) Removes a unit from an organization
ArrayList<ArrayList<String>>	informAgentRole(String RequestedAgentID) Requesting the list of roles and units in which an agent is in a specific moment.
ArrayList<ArrayList<String>>	informMembers(String UnitID, String RoleID, String PositionID) Indicates entities that are members of a specific unit.
ArrayList<String>	informRole(String RoleID, String UnitID) Provides a role description of a specific unit.
ArrayList<String>	informUnit(String UnitID) Provides unit description.
ArrayList<ArrayList<String>>	informUnitRoles(String UnitID) Used for requesting the list of roles that have been registered inside a unit.
String	jointUnit(String UnitID, String ParentUnitID) Update the parent unit
String	leaveRole(String RoleID, String UnitID) Service used for leaving a role inside a specific unit.
int	quantityMembers(String UnitID, String RoleID, String PositionID) Provides the number of current members of a specific unit.
String	registerRole(String RoleID, String UnitID, String AccessibilityID, String VisibilityID, String PositionID) Creates a new role inside a unit
String	registerUnit(String UnitID, String TypeID, String ParentUnitID, String CreatorID) Creates a new empty unit in the organization, with a specific structure, creatorName and parent unit.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

OMSProxy

public OMSProxy(BaseAgent agent,
                String OMSServiceDescriptionLocation)

This class gives us the support to access to the services of the OMS

Parameters:

agent - is a Magentix2 agent, this agent implemented the communication protocol.

OMSServiceDesciptionLocation - The URL where the owl's document is located.

OMSProxy

public OMSProxy(CProcessor agent,
                String OMSServiceDescriptionLocation)

OMSProxy

public OMSProxy(BaseAgent agent)

This class gives us the support to accede to the services of the OMS, Checked that the data contained in the file configuration/Settings.xml, the URL ServiceDescriptionLocation is not empty and is the correct path.

Parameters:

agent - is a Magentix2 Agent, this agent implemented the communication protocol

OMSProxy

public OMSProxy(CProcessor myProcessor)

Method Detail

buildOrganizationalMessage

public ACLMessage buildOrganizationalMessage(String OrganizationID)
                                      throws THOMASException

Builds a new organizational message with the appropriate receivers according to the type of unit and position of the role that the agent is performing

Parameters:

OrganizationID - represents the ID of the organization to which the agent wants to send a message

Returns:

returns the ACL message built

Throws:

THOMASException - If unit not found, the agent is not inside the unit, the agent not play any role or the agent only play the role creator.

leaveRole

public String leaveRole(String RoleID,
                        String UnitID)
                 throws THOMASException

Service used for leaving a role inside a specific unit.

Parameters:

RoleID - Identifier of the role

UnitID - Identifier of the organization unit

Returns:

Status if result is OK

Throws:

THOMASException - If the role or unit not exists, the agent not play the role or some parameter is empty or is invalid

informAgentRole

public ArrayList<ArrayList<String>> informAgentRole(String RequestedAgentID)
                                             throws THOMASException

Requesting the list of roles and units in which an agent is in a specific moment.

Parameters:

RequestedAgentID - Identifier of the agent requested

Returns:

ArrayList> The array list is formed by array lists of strings, each array list is formed by the fields (strings) role and unit

Throws:

THOMASException - If the agent not exists or some parameter is empty or is invalid

informMembers

public ArrayList<ArrayList<String>> informMembers(String UnitID,
                                                  String RoleID,
                                                  String PositionID)
                                           throws THOMASException

Indicates entities that are members of a specific unit. Optionally, it is possible to specify a role and position of this unit, so then only members playing this role or position are detailed.

Parameters:

UnitID - Identifier of the unit

RoleID - Identifier of the role

PositionID - Identifier of the position inside the unit, such as member, supervisor or subordinate

Returns:

ArrayList> The array list is formed by array list of strings, each array list is formed by the fields (strings) agent name and role name

Throws:

THOMASException - If unit not found, the role is not inside the unit, the agent is not allowed or some parameter is invalid

informRole

public ArrayList<String> informRole(String RoleID,
                                    String UnitID)
                             throws THOMASException

Provides a role description of a specific unit.

Parameters:

RoleID - Identifier of the role

UnitID - Identifier of the unit

Returns:

ArrayList The array list is formed by the fields (strings) position, visibility and accessibility

Throws:

THOMASException - If unit not found, the role is not is not registered in the unit, the agent is not allowed, or some parameter is empty or is invalid

informUnit

public ArrayList<String> informUnit(String UnitID)
                             throws THOMASException

Provides unit description.

Parameters:

UnitID - Identifier of the unit

Returns:

ArrayList The array list is formed by the fields (strings) unit type and parent name

Throws:

THOMASException - If unit not found, the agent not play any role in unit or parent unit or some parameter is empty or is invalid

informUnitRoles

public ArrayList<ArrayList<String>> informUnitRoles(String UnitID)
                                             throws THOMASException

Used for requesting the list of roles that have been registered inside a unit.

Parameters:

UnitID - Identifier of the unit

Returns:

ArrayList> The array list is formed by array list of strings, each array list is formed by the fields (strings) role name, position, visibility and accessibility

Throws:

THOMASException - If unit not found

quantityMembers

public int quantityMembers(String UnitID,
                           String RoleID,
                           String PositionID)
                    throws THOMASException

Provides the number of current members of a specific unit. Optionally, if a role and position is indicated then only the quantity of members playing this roles or position is detailed.

Parameters:

UnitID - Identifier of the unit

RoleID - Identifier of the role

PositionID - Identifier of the position inside the unit, such as member, supervisor or subordinate

Returns:

Integer Quantity of members

Throws:

THOMASException - If unit not found, the role is not inside the unit, the agent is not allowed or some parameter is invalid

registerRole

public String registerRole(String RoleID,
                           String UnitID,
                           String AccessibilityID,
                           String VisibilityID,
                           String PositionID)
                    throws THOMASException

Creates a new role inside a unit

Parameters:

RoleID - Identifier of the role

UnitID - Identifier of the unit

AccessibilityID - considers two types of roles: (internal) internal roles, which are assigned to internal agents of the system platform; and (external) external roles, which can be enacted by any agent.

VisibilityID - indicates whether agents can obtain information of this role from outside the unit in which this role is defined (public) or from inside (private).

PositionID - determines its structural position inside the unit, such as member, supervisor or subordinate.

Returns:

Status if result is OK

Throws:

THOMASException - If unit not found, the role is already registered in the unit, the agent is not allowed or some parameter is empty or is invalid

registerUnit

public String registerUnit(String UnitID,
                           String TypeID,
                           String ParentUnitID,
                           String CreatorID)
                    throws THOMASException

Creates a new empty unit in the organization, with a specific structure, creatorName and parent unit.

Parameters:

UnitID - Identifier of the unit

TypeID - indicates the topology of the new unit: (i) Hierarchy, in which a supervisor agent has control over other members; (ii) Team, which are groups of agents that share a common goal, collaborating and cooperating between them; and (iii) Flat, in which there is none agent with control over other members.

ParentUnitID - Identifier of the parent unit

CreatorID - The name of the new creator role

Returns:

Status if result is OK

Throws:

THOMASException - If unit already exists, if the parent unit not exists, the agent is not allowed or some parameter is empty or is invalid

jointUnit

public String jointUnit(String UnitID,
                        String ParentUnitID)
                 throws THOMASException

Update the parent unit

Parameters:

UnitID - Identifier of the unit

ParentUnitID - Identifier of the new parent unit

Returns:

Status if result is OK

Throws:

THOMASException - If unit or parent unit not found, the unit and parent unit are the same, the agent is not allowed or some parameter is empty or is invalid

deregisterRole

public String deregisterRole(String RoleID,
                             String UnitID)
                      throws THOMASException

Removes a specific role from a unit.

Parameters:

RoleID - Identifier of the role

UnitID - Identifier of the unit

Returns:

Status if result is OK

Throws:

THOMASException - If unit not found, the role is not registered in the unit, if not allowed or some parameter is empty or is invalid

deregisterUnit

public String deregisterUnit(String UnitID)
                      throws THOMASException

Removes a unit from an organization

Parameters:

UnitID - Identifier of the unit

Returns:

Status if result is OK

Throws:

THOMASException - If unit not found, if not allowed or some parameter is empty or is invalid

deallocateRole

public String deallocateRole(String RoleID,
                             String UnitID,
                             String TargetAgentID)
                      throws THOMASException

Forces an agent to leave a specific role

Parameters:

RoleID - Identifier of the role

UnitID - Identifier of the unit

TargetAgentID - Identifier of the agent

Returns:

Status if result is OK

Throws:

THOMASException - If unit or role not found, if target agent not play the role, the agent is not allowed or some parameter is empty or is invalid

allocateRole

public String allocateRole(String RoleID,
                           String UnitID,
                           String TargetAgentID)
                    throws THOMASException

Forces an agent to acquire a specific role

Parameters:

RoleID - Identifier of the role

UnitID - Identifier of the unit

TargetAgentID - Identifier of the agent

Returns:

Status if result is OK

Throws:

THOMASException - If unit or role not found, if target agent already play the role, the agent is not allowed or some parameter is empty or is invalid

acquireRole

public String acquireRole(String RoleID,
                          String UnitID)
                   throws THOMASException

Service used for acquiring a role inside a specific unit.

Parameters:

RoleID - Identifier of the role

UnitID - Identifier of the organization unit

Returns:

Status if result is OK

Throws:

THOMASException - If the role or unit not exists, the agent play the role or some parameter is empty or is invalid