Defining References for Object Types with Annotations

References allow users to navigate from one object to related objects. To model relationships other than membership, you can expose a method as a reference. That is, define a method that returns the set of related objects, and annotate it as a @TeaReference.

1. Define a reference method that accepts an object key as its parameter, and returns an array or java.util.Collection of the related objects as instances of com.tibco.tea.agent.types.AgentObjectIdentifier.
   The agent library invokes this reference method in context of the source object, and supplies its object key as the parameter. Annotate that parameter using @KeyParam. Top-level and singleton object types can omit this parameter (and its annotation), because only one such object can exist.
   For example, in TIBCO Enterprise Messaging System, administrators can define a set of queues. The getQueues method returns an array or java.util.Collection of AgentObjectIdentifier references that represent those queues.

   public AgentObjectIdentifier[] getQueues(
       @KeyParam final String key){
       ...
   }

   public Collection<AgentObjectIdentifier> getQueues(
       @KeyParam final String key){
       ...
   }

2. Annotate the method as a reference using @TeaReference. For example, the getQueues method is marked as a reference using the TeaReference annotation.

   @TeaReference(name = "queues",
       referenceType = "queueType",
       objectType = "serverType")
   public AgentObjectIdentifier[] getQueues(@KeyParam final String key){
       ...
   }

   @TeaReference(name = "queues",
       referenceType = "queueType",
       objectType = "serverType")
   public Collection<AgentObjectIdentifier> getQueues(@KeyParam final String key){
       ...
   }

   Include the referenceType attribute to indicate the type of element that the object identifiers represent.
   If the source class defines more than one object type, then include the objectType attribute, to distinguish the TeaObjectType to which the reference method applies (as the source object).