CRecordLaunchApplication

A record to launch an application.

This message belongs to the application factory collector API.

{
  "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."
    }
  ]
}

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
{
    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);
}

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;
    }
}