CRecordLaunchApplication

The message CRecordLaunchApplication is used to start applications. Applications can be hosted and started on any node. The message is first sent to the Application Collector Service, which selects an appropriate factory instance (load balancing) and then forwards the message to the application factory.

This message belongs to the application factory collector API.
The Application Collector Service is located in the plugin NY_ApplicationFactoryCollectorPlugIn.

{
  "id": "d0140763-3cb9-4bd0-8c5f-1562c6e50216",
  "name": "LAUNCH_APPLICATION",
  "isService": "false",
  "namespaces": "",
  "description": "Create and launch an application instance.",
  "slots": [
    {
      "key": "1",
      "name": "APPLICATION_ID",
      "direction": "REQUEST",
      "mandatory": "true",
      "type": "UUID",
      "description": "The ID of the application."
    },
    {
      "key": "2",
      "name": "REMOTE_SKIN_CLIENT_NODE",
      "direction": "REQUEST",
      "mandatory": "true",
      "type": "NODE_ADDRESS",
      "description": "Optional: The node address of the RemoteSkin client."
    },
    {
      "key": "3",
      "name": "REMOTE_SKIN_TARGET",
      "direction": "REQUEST",
      "mandatory": "true",
      "type": "TARGET_ADDRESS",
      "description": "Web Client: An existing RemoteSkin target."
    },
    {
      "key": "4",
      "name": "PROPERTIES",
      "direction": "REQUEST",
      "mandatory": "false",
      "type": "STRING_PROPERTIES",
      "description": "Properties for launching the application."
    },
    {
      "key": "10",
      "name": "APP_INSTANCE_ID",
      "direction": "ANSWER",
      "mandatory": "false",
      "type": "UUID",
      "description": "The instance ID of the launched application."
    },
    {
      "key": "11",
      "name": "INSTANCE_ADDRESS",
      "direction": "ANSWER",
      "mandatory": "false",
      "type": "TARGET_ADDRESS",
      "description": "The address of the main target of the application."
    }
  ]
}

Arguments

Starting an application requires a valid session token with the appropriate rights.

• APPLICATION_ID: The ID of the application that is to be started.
• REMOTE_SKIN_CLIENT_NODE: Optional, for Swing applications: The client node address.
• REMOTE_SKIN_TARGET: For web applications: The client address, more precisely the address of the target of the web socket connection.
• PROPERTIES: The arguments to be given to the application.
• APP_INSTANCE_ID: Response: The instance ID of the started application.
• INSTANCE_ADDRESS: Response: The target address of the started application.

Usage

Sending the message

Example of use (after generating of the class CRecordLaunchApplication):

In any case, starting an application naturally requires the ID of the application in the form of a UUID. In most cases, a session token is required for authentication. This is at your convenience. If UI output is desired, the node address (for Swing) or the target address of the websocket connection (Web) must also be specified. Optionally, properties of the starting application can be specified.

// request
private void launchApplication(@NotNull final UUID aApplicationId,
                               final byte[] aSessionToken,
                               @Nullable final CNodeAddress aClientNodeAddress,
                               @Nullable final CTargetAddress aClientTargetAddress,
                               @Nullable final CStringProperties aProperties) throws CException
{
    // The message is sent to the AppCollector microservice.
    final IId microserviceId = CIdFactory.fromObject("NY_ApplicationFactoryCollector");
    final CEnvelope env = CEnvelope.forMicroService(microserviceId);
    
    // Optional (Only if certain user rights are required to start the application)
    env.setSessionToken(aSessionToken);

    final CRecord record = CRecordLaunchApplication.create();
    CRecordLaunchApplication.setApplicationId(record,
                                              aApplicationId);
    // Optional for RemoteSkin Swing applications: The client node address
    CRecordLaunchApplication.setRemoteSkinClientNode(record,
                                                     <aClientNodeAddress);
    // Optional for RemoteSkin Web applications: The web socket connection target to the browser renderer
    CRecordLaunchApplication.setRemoteSkinTarget(record,
                                                 aClientTargetAddress);
    // Optional: properties for the application
    CRecordLaunchApplication.setProperties(record,
                                           aProperties);
    sendRequest(env,
                record);
}

Dealing with the response

The response to the request can be caught as usual via a MessageHandler.

// for the constructor of your target
addMessageHandler(CRecordLaunchApplication.ID,
                  this::asyncLaunchApplication);

The returned target address can be used for communication with the application. In addition, if the application supports it, a message can be sent to terminate the application.

// the message handler
private boolean asyncLaunchApplication(@NotNull final CEnvelope aEnvelope,
                                       @NotNull final CRecord aRecord)
{
    if (aEnvelope.isAnswer())
    {
        if (aEnvelope.getResultCode() == CResultCode.SUCCESS)
        {
            final UUID appInstanceId = CRecordLaunchApplication.getAppInstanceId(aRecord,
                                                                                 null);
            final CTargetAddress instanceAddress = CRecordLaunchApplication.getInstanceAddress(aRecord,
                                                                                               null);
            // ...
        }
        else
        {
            // ...
        }
        return true;
    }
    else
    {
        return false;
    }
}

See also:

• How to build a message
• application factory collector API
• NY_ApplicationFactoryCollectorPlugIn