Gateway helper class usage instructions

Implement interceptor features

Interceptors apply only to non-HTTP services.

The mobilegw-unify-spi-adapter.jar file uses Java reflection to call business methods specified by OperationType. You can implement the interceptors defined in the Service Provider Interface (SPI) package to extend this process.

The gateway SPI package defines two interceptors: the AbstractMobileServiceInterceptor abstract class and the MobileServiceInterceptor interface.

AbstractMobileServiceInterceptor

The AbstractMobileServiceInterceptor class provides four methods: beforeInvoke, afterInvoke, throwsInvoke, and getOrder. The afterInvoke method has two overloads: one accepts a business return object, and the other accepts a JSON string converted from the object.

As shown in the preceding figure, the interceptor covers three scenarios:

• Before the method is called: The beforeInvoke method has a return value. If this method returns a non-empty value, the gateway considers the interception successful. It then skips the beforeInvoke methods of the remaining interceptors and the business method call, and proceeds directly to the afterInvoke method of that interceptor.

• After the method is called: The afterInvoke method has two overloads. The first accepts an object returned by the business, has no return value, and runs for all interceptors. The second accepts a JSON string converted from the object and can return modified data. If this overload returns a non-empty value, the gateway considers the interception successful and skips subsequent interceptors.

• When an exception occurs in the method: The throwsInvoke method has no return value and is executed for all interceptors when an exception occurs in your business logic.

MobileServiceInterceptor

The MobileServiceInterceptor inherits the Ordered interface from the framework, so you can implement the getOrder method to specify the execution order. A smaller value indicates higher priority.

Usage example

1. Create your own interceptor class that inherits the AbstractMobileServiceInterceptor class or implements the MobileServiceInterceptor interface.

   public class MyInterceptor implements MobileServiceInterceptor {
   
    /*
     Description of parameters
        method: The business method defined by @OperationType.
        args: An object array that contains the input parameters for the business method. The number of input parameters equals the size of the array. Perform type conversion as needed.    
        target: The instance of the business interface.
     Description of the return value:
        Object: You can return data in the interceptor. If the return value is not empty, the gateway considers the call intercepted and does not call the business method.
            It also skips the beforeInvoke methods of other interceptors and directly executes the afterInvoke method.       
    */
   
    @Override
    public Object beforeInvoke(Method method, Object[] args, Object target) {
        //Do Something
        return null;
    }
   
    /*
    *Description of parameters
    *returnValue: The object returned by the business method.
    * Other parameters are the same as described previously.  
    */
    @Override
    public void afterInvoke(Object returnValue, Method method, Object[] args, Object target) {
        //Note: The input parameter here is the Object returned by your business.
    }
   
    @Override
    public String afterInvoke(String returnJsonValue, Method method, Object[] args, Object target) {
        //Note: The input parameter here is the JSON-formatted string converted from the object returned by your business.
        //You can return new JSON-formatted data.
        return null;
    }
   
    @Override
    public void throwsInvoke(Throwable t, Method method, Object[] args, Object target) {
    }
   
    @Override
    public int getOrder() {
        //The highest priority (smallest value) and the lowest priority (largest value).
        return 0;
    }
   }

2. Publish the implemented class MyInterceptor as a bean.

   • For Spring Boot, add the @Service annotation to the class.

     @Service
     public class MyInterceptor implements MobileServiceInterceptor{}

   • For Spring, declare the bean in the xml configuration file.

     <bean id="myInterceptor" class="com.xxx.xxx.MyInterceptor"/>

MobileRpcHolder helper class

MobileRpcHolder is a static helper class in mobilegw-unify-spi-adapter.jar that holds request-related information. The main fields are:

Map<String, String> session;     // Stores the request session.
Map<String, String> header;      // Stores the request header information.
Map<String, String> context;     // Stores the context information for the gateway call.
String        operationType;     // Stores the operationType for this request.

Before the gateway calls your business service (specified by OperationType), it populates MobileRpcHolder with information from the forwarded MobileRpcRequest. This information is cleared after the call completes.

The lifecycle of MobileRpcHolder persists throughout the service call and is cleared after the call completes.

You can also set custom information in MobileRpcHolder. This information persists throughout the business service call, allowing the service to retrieve it at any time. You can use an interceptor to dynamically modify MobileRpcHolder before and after the method call.

The following example shows how to modify and retrieve a session with MobileRpcHolder.

Usage example

The following steps show how to modify and retrieve a session.

1. Modify the session. Create an interceptor as described previously. The following code intercepts the call before a method runs:

    @Override
    public Object beforeInvoke(Method method, Object[] args, Object target) {
        Map<String, String> session = MobileRpcHolder.getSession();
        session.put("key_test", "value_test");
        MobileRpcHolder.setSession(session);
    }

   This lets you modify the session information in MobileRpcHolder.

2. Retrieve the session. You can access the session information from within your service.

    @OperationType("com.alipay.account.query")
    public String mock2(String s) {
        Map<String, String> session = MobileRpcHolder.getSession();
    }

   The methods for modifying and retrieving other information, such as the header and context, are similar.

    // Get all header information.
    Map<String,String> headers = MobileRpcHolder.getHeaders();
    // The context information here refers to the context information in the request.
    Map<String,String> context = MobileRpcHolder.getRequestCtx(); 
    // Get the OperationType.
    String opt = MobileRpcHolder.getOperationType();

Use gateway error codes

Mobile Gateway Service has its own error code specifications. For more information, see Gateway result codes.

The error code BizException 6666 is thrown when a business exception occurs.

To return a different error code for a specific error, throw an RpcException(ResultEnum resultCode) to control errors at the Remote Procedure Call (RPC) layer. For example, if resultCode=1001, "No permission to access" is returned to the client.

Code example

@Override
public String mock2(String s) throws RpcException {
    try{
        test();
    }catch (Exception e){
        throw new RpcException(IllegalArgument);
    }
    return "11111111";
}

Custom error codes

To use custom error codes, avoid throwing exceptions from your business methods.

If a business method throws an exception, the gateway returns status code 6666. A client that receives this code treats the call as failed and does not parse the returned business data. The client parses business data only when it receives the success status code 1000.

To implement custom error codes, the server and client must agree on a set of error codes. In your business method, catch all exceptions and include the appropriate custom error code in the returned data. This ensures the gateway always returns success code 1000, even when a business exception occurs. The client then parses the returned data to handle the custom error code.