Skip to main content

OnExternal

Introduction​

Accessing and extending the external server is one of the communication methods provided by the framework, mainly used for interaction between logic servers and external servers. This article explains how to obtain required data from the external server. Developers can implement interaction with external servers by extending the OnExternal interface. Through this extension, the framework easily supports features such as:

Now, we use a userIp example to learn how to extend it.

Example Source Code​

see https://github.com/iohao/ionet-examples

path : ionet-cookbook-code

  • UserIpOnExternal
  • OnExternalAction

How to Extend​

  • code 4: get the current user.
  • code 7: get the current user's IP.
  • code 8: set the response value to the requester.
  • code 13: set the extension marker ExternalTemplateId.
public class UserIpOnExternal implements OnExternal {
    @Override
    public void process(byte[] payload, int payloadLength, OnExternalContext context) {
        UserSession userSession = context.getUserSession();
        ActionErrorEnum.dataNotExist.assertNonNull(userSession);
        // get userIp
        String ip = userSession.getIp();
        context.response().setPayload(ip);
    }

    @Override
    public int getTemplateId() {
        return MyOnExternalTemplateId.userIp;
    }
}

public interface MyOnExternalTemplateId {
    /** get userIp */
    int userIp = 1;
}

Configuration​

Add the implementation class to OnExternalManager.

class OneApplication {
    static void main() {
        OnExternalManager.register(new UserIpOnExternal());
        ...
        new RunOne()
                ...
                .startup();
    }
}

How to Use​

You can directly access the user's external server through the callExternal series methods.

@ActionController(OnExternalCmd.cmd)
public final class OnExternalAction {
    @ActionMethod(OnExternalCmd.userIp)
    private String getIp(FlowContext flowContext) {
        var externalResponse = flowContext.callExternal(MyOnExternalTemplateId.userIp);
        return externalResponse.getPayloadAsString();
    }
}

Count Online Users​

From the previous example, we know how to get userIp, but that example accesses only a single external server. Now we implement an extension for online user counting. If multiple external servers are running, we need to know the current online count of each external server. This extension interacts with multiple external servers at the same time.

  • code 4: get UserSessions of the current external server.
  • code 6: set the response value to the requester.
  • code 11: set the extension marker ExternalTemplateId.
  • code 23: add the implementation class to OnExternalManager.
public final class UserOnlineCountOnExternal implements OnExternal {
    @Override
    public void process(byte[] payload, int payloadLength, OnExternalContext context) {
        UserSessions<?, ?> userSessions = context.userSessions();
        int countOnline = userSessions.countOnline();
        context.response().setPayload(countOnline);
    }

    @Override
    public int getTemplateId() {
        return MyOnExternalTemplateId.userOnlineCount;
    }
}

public interface MyOnExternalTemplateId {
    /** get userIp */
    int userIp = 1;
    int userOnlineCount = 2;
}

class OneApplication {
    static void main() {
        OnExternalManager.register(new UserOnlineCountOnExternal());
        ...
    }
}

How to Use

  • code 7: use the callExternalCollect series methods to directly access all external servers.
  • code 8: iterate through responses from each external server.
  • code 10: get the value set in UserOnlineCountOnExternal.
@ActionController(OnExternalCmd.cmd)
public final class OnExternalAction {
    @ActionMethod(OnExternalCmd.userOnlineCount)
    private int userOnlineCount(FlowContext flowContext) {
        int onlineCount = 0;

        var responseCollectExternal = flowContext.callExternalCollect(MyOnExternalTemplateId.userOnlineCount);
        for (var externalResponse : responseCollectExternal.getResponseList()) {
            int externalServerId = externalResponse.getExternalServerId();
            int count = externalResponse.getPayloadAsInt();
            log.info("externalServerId:{}, count:{}", externalServerId, count);

            onlineCount += count;
        }

        return onlineCount;
    }
}

How to Set Request Parameters​

The two extension examples above do not demonstrate request parameters, but in real business scenarios, we may need to pass request parameters to OnExternal extension classes. The callExternalCollect and callExternal methods provide overloads. Developers can pass request parameters through these overloads. See source code AttachmentUpdateOnExternal for details.


Set Request Parameters

...
void test() {
    byte[] payload = ...
    flowContext.callExternal(MyOnExternalTemplateId.xxx, payload);
}

Get Request Parameters

public final class AttachmentUpdateOnExternal implements OnExternal {
    @Override
    public void process(byte[] payload, int payloadLength, OnExternalContext context) {
        var userSession = context.getUserSession();
        if (userSession != null) {
            userSession.setAttachment(ByteKit.getPayload(payload, payloadLength));
        } else {
            context.response().setError(ActionErrorEnum.dataNotExist);
        }
    }

    ...
}

Summary​

With enough imagination, you can do many things through the OnExternal interface. By extending this interface, you can interact with external servers and obtain data.