Defining Operations for Objects

Any registered object type can expose a method as an operation available to TIBCO Enterprise Administrator server and the user interface.

1. Define a method signature. The method can have parameters or return simple types or objects that conform to the java bean specification. For example, the addUser() method maps a user from the given LDAP realm to a set of roles.

   public void addUser(String realm, LdapUserMapping config) {
           // the code
           }

2. Add annotations to mark the method as an operation and define its parameters.

   Annotations	Description
   TeaOperation	Marks the method as an operation. The annotation defines the name and description of the operation.
   KeyParam	A key for the object that is the target for this operation. This attribute can be skipped for an operation on top-level types, as there can be only one instance of top level object per agent.
   TeaParam	Each parameter is annotated with a parameter name, an optional description and a default value. This is required as Java does not preserve names of the parameters at runtime.
   TeaRequires (optional)	The annotation should go together with the TeaOperation annotation. It defines list of permissions required to invoke given operation. If the operations does not have permission annotation, it is considered 'Read-only', and it will require only 'Read' permission.

   For example, the addUser() method is marked as an operation using the TeaOperation annotation.

   @TeaRequires(value={"TEA_ADMIN","TEA_USER", "TEA_SUPER_USER"} )
   @TeaOperation(name ="add-user", description = "Create new user")
   public void addUser(
   	   @KeyParam final String key,
   	   @TeaParam(name = "realm") final String realm,
   	   @TeaParam(name = "user") final Object config) {
   		     // code
   }

   The annotation is sufficient to expose this operation in the default UI. The operation bar on the object has a button for adding a user which opens a default form. The operation is available in the shell as well.

   Note: To return a JSON object, the agent library supports Jackson databinding through Jackson or JAXB annotations. The agent library does not support org.json module for Jackson. You can write plain java objects with annotation, or if you want to use generic types, you can use the Jackson databind API or use Map<String, Object>, which is a a map of maps representing the JSON structure.
3. Add parameters that represent file artifacts. Use the TeaParam annotation on a method parameter with type javax.activation.DataSource. For example:

   @TeaOperation(name = "upload", description = "Upload File")
   public String uploadFile(
       @TeaParam(name = "file", description = "File to Upload") DataSource upload) throws IOException {
    
     InputStream inputStream = upload.getInputStream();
     ByteArrayOutputStream outputStream = new ByteArrayOutputStream();
     byte[] buffer = new byte[1024];
     int read;
     while ((read = inputStream.read(buffer)) != -1) {
       outputStream.write(buffer, 0, read);
     }
     inputStream.close();
     outputStream.close();
     File file = File.createTempFile(upload.getName(), null);
     FileOutputStream fileOutputStream = new FileOutputStream(file);
     outputStream.writeTo(fileOutputStream);
     fileOutputStream.close();
     return upload.getName();
   }

4. Specify the permissions required to invoke the operation. The TeaRequires annotation lists all the permissions required to invoke the operation in addition to the Read permission for the parent object. If the annotation is not present, anyone with the Read permission for the parent object can invoke it. For example:

   @TeaRequires(value={"TEA_ADMIN","TEA_USER", "TEA_SUPER_USER"} )
   @TeaOperation(name ="add-user", description = "Create new user")
   public void addUser(
   	@KeyParam final String key,
   	@TeaParam(name = "realm") final String realm,
   	@TeaParam(name = "user") final Object config) {
   		// code
   }

   You must define the Permission names (in this case, "TEA_ADMIN", "TEA_USER", "TEA_SUPER_USER") which is displayed in the UI for creating privileges and roles.

   Note: If there are two agents for the same object type, ensure that they have the same operation name and number. This is to ensure that when you invoke an operation, you can select the agent on which you want to execute the operation from the drop-down list on the Web-based GUI.

   Caution: When multiple agents coexist with each other, you should not modify an existing operation in the new version of the agent. Do not add or delete parameters to an existing operation. Also, ensure that you do not modify the signature of an existing TeaOperation.