Creating a Management Resource

Publishing a Management Resource

Creating a management resource is done through the use of the Fabric3 org.fabric3.api.annotation.management annotations. Note management components must be composite-scoped. Below is a simple component that exposes a property and an operation:

@Scope("COMPOSITE")
@Management(path="/myapp/audit")
public class AuditServiceImpl implements AuditService {
 
    @ManagementOperation
    public void setAuditLevel(String level) {
        //...
    }
     
    @ManagementOperation
    public String getAuditLevel() {
        //...
    }
 
    @ManagementOperation
    public void startAudit() {
        // ...
    }
 
    @ManagementOperation
    public void stopAudit() {
        // ..
    }
}

The above component will be published at http:<runtime address:port>/management/myapp/audit. Components are published relative to http:<runtime address:port>/management using the path attribute of the @Management annotation. Methods annotated with @ManagementOperation are exposed relative to the resource root. For example, the URI for stopAudit will be http:<runtime address:port>/management/myapp/audit/stopAudit. If a path is also present on the @ManagementOperation annotation, it will be added to the root path when calculating the URI for a method. For example, if the stopAudit operation was annotated as follows:

@ManagementOperation (path="stop")
public void stopAudit() {
   // ..
}

the URI would be: http:<runtime address:port>/management/myapp/audit/stop.

If the type attribute of @ManagementOperation is not specified, the HTTP verb is calculated from the method name as follows:

• If the method starts with "delete" the HTTP verb is DELETE
• If the method starts with "set" the HTTP verb is POST
• If the method starts with "create" the HTTP verb is PUT
• Otherwise the HTTP verb is GET

org.fabric3.api.annotation.management.OperationType defines the possible values for the type attribute.

Obtaining the HTTP Request

Sometimes it is necessary to obtain the HTTP Servlet Request associated with a management operation, for example, to receive an InputStream to read binary contants associated with a management request. This is done by having the operation take HttpServletRequest as a parameter:

    @ManagementOperation(type = OperationType.PUT, path = "contribution")
    public String receiveBinaryData(HttpServletRequest request) throws ResourceException {
        // ...
    }
}

Customizing an Operation Response

TODO include description of the org.fabric3.management.rest.model package.

Authorization

HTTP authorization can be enabled at an resource or operation level using the readRoles and writeRoles parameters for @Management and the rolesAllowed parameter for @ManagementOperation. By default on system components, readRoles is set to ROLE_FABRIC3_ADMIN and ROLE_FABRIC3_OBSERVER while writeRoles is set to ROLE_FABRIC3_ADMIN. The following example enables custom authorization:

@Scope("COMPOSITE")
@Management(readRoles={"ROLE_OPERATIONS", "ROLE_ADMIN"}, writeRoles={"ROLE_ADMIN"})
public class AuditServiceImpl implements AuditService {
 
    @ManagementOperation(rolesAllowed={"ROLE_SUPER_ADMIN"})
    public void setAuditLevel(String level) {
        // ...
    }
     
    @ManagementOperation(rolesAllowed={"ROLE_SUPER_ADMIN"})
    public String getAuditLevel() {
        // ...
    }
 
    @ManagementOperation
    public void startAudit() {
        // ...
    }
 
    @ManagementOperation
    public void stopAudit() {
        // ..
    }
}

Cluster Propagation

Note that all POST operations performed to a cluster member will be automatically propagated across a zone.