Defining Operations

To expose a method of an object type as an operation, annotate it as @TeaOperation. End users of TIBCO Enterprise Administrator server can invoke operations.

1. Declare the method signature.
   An operation method can take parameters. An operation can return either a simple type or an object that conforms to the Java bean specification.
   For example, a Tomcat agent could support a create() method to add a new server to the Tomcat cluster.

   public void create(
       final String name,
       final Integer port,
       Integer ajpPort,
       Integer shutdownPort)
       ...
   

   Note: If multiple agents manage the same object type, they must expose the same set of operations. Furthermore, corresponding operations must have identical names and method signatures. This restriction ensures that users can invoke an operation on either agent (selecting it from a drop-down menu in the GUI).

   Caution: If multiple versions of an agent must coexist simultaneously, do not modify the method signature of an existing operation in the new version of the agent.
2. Annotate the method as a @TeaOperation. In our continuing example, we use the annotation to rename the operation and to supply a description string—both become part of the product's GUI in the TIBCO Enterprise Administrator server. We also supply a method type, indicating that this operation effects changes in the product.

   @TeaOperation(name = "create server",
       description = "Create a Tomcat server instance",
       methodType = MethodType.UPDATE)
   public void create(
       final String name,
       final Integer port,
       Integer ajpPort,
       Integer shutdownPort)
       ...
   

3. Optional. Annotate the permissions that this operation requires.

   @TeaOperation(name = "create server",
       description = "Create a Tomcat server instance",
       methodType = MethodType.UPDATE)
   @TeaRequires(value = TomcatAgent.LIFECYCLE_PERMISSION)
   public void create(
       ...
   

   Users that have any of the required permissions for the object can execute the operation.
   If you omit the @TeaRequires annotation, the default requirement is for the minimum permission, which is read.
   Define permissions using the @TeaPermission annotation.
4. Annotate the method's parameters as parameters of the operation.

   Annotation	Description
   @KeyParam	If one of the parameters receives an object key, then annotate that parameter with @KeyParam. The server automatically supplies the target object as the argument of this parameter. Top-level and singleton object types can omit this annotation, because they have only one instance.
   @TeaParam	Annotate each parameter with a parameter name, an optional description and an optional defaultValue. The name attribute is required because Java does not preserve parameter names at run time. The defaultValue attribute of TeaParam is optional. If you choose to provide it, its value should be provided in the JSON format.

   @TeaOperation(name = "create server",
       description = "Create a Tomcat server instance",
       methodType = MethodType.UPDATE)
   public void create(
       @TeaParam(name = "name",
            description = "Name of the Tomcat instance")
            final String name,
       @TeaParam(name = "port",
            description = "Port for HTTP connector")
            final Integer port,
       @TeaParam(name = "ajpport",
            defaultValue = "-1",
            description =
              "Port for AJP connector.
               If value is -1, agent randomly picks a port.")
            Integer ajpPort,
       @TeaParam(name = "shutdownport",
            defaultValue = "-1",
            description =
              "Port for shutting down tomcat.
               If value is -1, agent randomly picks a port.")
            Integer shutdownPort)
       ...
   
   @TeaOperation(name = "changePort", objectType = "server",
       description = "Change the server port")
   @TeaRequires(value = { TomcatAgent.UPDATE_PERMISSION })
   public void changePort(
       @KeyParam final String key,
       @TeaParam(name = "port", description = "Change to this port.")
           final int port)
       ...
   

   At this stage, these annotations suffice to expose these operations in the default GUI and the shell UI. The operation bar on the object displays a button that creates a server. That button opens a default form so the user can enter argument values.
5. Prepare the return value.
   An operation method can return a value to the TIBCO Enterprise Administration server. The form of that value could require preparation within the agent code.

   Return Type	Description
   TeaObject	No further preparation. The agent library automatically translates the TeaObject instance to JSON format before returning it to the server.
   Map<String, Object>	No further preparation. If the operation returns a map of maps, the agent library automatically converts it to JSON format before returning it to the server.
   Java Object	The agent library uses Jackson to serialize the Java object to JSON format before returning it to the server. Two options are available: Annotate the Java class using Jackson or JAXB annotation. Arrange translation using the Jackson databinding API. Note: The agent library does not support Jackson's org.json module.