Unknown macro: {style}

.ia-secondary-container

Unknown macro: { margin}
Unknown macro: {div}
Kaa releases
Unknown macro: {div}
Shortcuts

Page tree
Skip to end of metadata
Go to start of metadata

Introduction

To implement a custom transport, you need to complete the following steps.

  1. Design and compile a configuration schema.
  2. Implement the TransportConfig interface.
  3. Implement Transport.
  4. Provision the transport in a Bootstrap server and/or an Operations server.

We recommend that you use one of the existing transport implementations as a reference and also review the transports design reference.

Please note that once a new transport is implemented, you will most likely need to implement a corresponding transport channel for one or multiple endpoint SDK platforms. 

Transport configuration schema

A transport configuration schema is an Avro compatible schema that defines configuration parameters for the transport. The following parameters in the schema affect Kaa Admin UI layout.

  • minRowCount - specifies a minimum number of rows in a UI table (If you are using arrays in your schema, you can specify a minimum number of elements in an array with this parameter)
  • displayName - displays the name of the field on UI
  • displayNames - displays the name of each enumeration symbol on UI (only for enumeration fields in the schema)
  • default - displays the default value of the field on UI
  • optional - defines whether the field on UI is optional or mandatory
  • weight - defines a relative width of the corresponding column on UI (only for arrays in the schema)

The following example illustrates a simple transport configuration schema with two fields (host and port).

{  
    "namespace":"org.kaaproject.kaa.server.transport.custom.config",
    "type":"record",
    "name":"CustomConfig",
    "fields":[  
        {  
            "name":"host",
            "type":"string"
        },
        {  
            "name":"port",
            "type":"int"
        }
    ]
}

Once you have prepared your schema, you can compile it using the following command.
java -jar /path/to/avro-tools-1.7.7.jar compile schema <schema file> <destination>
For more information, refer to Compiling the schema. It is also possible to integrate the schema compilation with avro-maven-plugin.

Transport descriptor implementation

Once you have defined and compiled a transport configuration schema, you can proceed to the implementation of a transport descriptor.

A transport descriptor should implement the TransportConfig interface and be annotated with the KaaTransportConfig annotation for the provisioning purposes.

Note: all transport descriptors should be inside the org.kaaproject.kaa.server.transport package or its subpackages.

The following example illustrates a transport descriptor implementation based on the schema defined in the previous section. 

package org.kaaproject.kaa.server.transport.custom.config;
import org.apache.avro.Schema;
import org.kaaproject.kaa.server.common.zk.ServerNameUtil;
import org.kaaproject.kaa.server.transport.KaaTransportConfig;
import org.kaaproject.kaa.server.transport.Transport;
import org.kaaproject.kaa.server.transport.TransportConfig;
import org.kaaproject.kaa.server.transport.TransportService;
 
/**
 * Configuration for the custom transport
 */
@KaaTransportConfig
public class CustomTransportConfig implements TransportConfig {
 
    private static final String CUSTOM_TRANSPORT_NAME = "org.kaaproject.kaa.server.transport.tcp";
    private static final int CUSTOM_TRANSPORT_ID = ServerNameUtil.crc32(CUSTOM_TRANSPORT_NAME);
    private static final String CUSTOM_TRANSPORT_CLASS = "org.kaaproject.kaa.server.transports.tcp.transport.TcpTransport";
    private static final String CUSTOM_TRANSPORT_CONFIG = "custom-transport.config";
 
    public CustomTransportConfig() {
        super();
    }
 
    /**
     * Returns the transport id. The transport id must be unique.
     * 
     * @return the transport id
     */
    @Override
    public int getId() {
        return CUSTOM_TRANSPORT_ID;
    }
 
    /**
     * Returns the transport name. There is no strict rule for this
     * name to be unique.
     * 
     * @return the transport name
     */
    @Override
    public String getName() {
        return CUSTOM_TRANSPORT_NAME;
    }
 
    /**
     * Returns the class name of the {@link Transport} implementation.
     * 
     * @return the class name of the {@link Transport} implementation
     */
    @Override
    public String getTransportClass() {
        return CUSTOM_TRANSPORT_CLASS;
    }
 
    /**
     * Returns the avro schema of the {@link Transport} configuration.
     * 
     * @return the avro schema of the {@link Transport} configuration
     */
    @Override
    public Schema getConfigSchema() {
        return CustomConfig.getClassSchema();
    }
 
    /**
     * Returns the configuration file name. This configuration file may
     * be used by {@link TransportService} to initialize and configure
     * the corresponding {@link Transport}.
     * 
     * @return the configuration file name
     */
    @Override
    public String getConfigFileName() {
        return CUSTOM_TRANSPORT_CONFIG;
    }
}

 

Transport implementation

All transport implementations should implement the Transport interface. We recommend extending AbstractKaaTransport for convenience.

The following example illustrates a transport implementation based on the defined transport configuration schema. 

package org.kaaproject.kaa.server.transports.tcp.transport;
import java.nio.ByteBuffer;
import org.kaaproject.kaa.server.transport.AbstractKaaTransport;
import org.kaaproject.kaa.server.transport.KaaTransportConfig;
import org.kaaproject.kaa.server.transport.SpecificTransportContext;
import org.kaaproject.kaa.server.transport.Transport;
import org.kaaproject.kaa.server.transport.TransportLifecycleException;
import org.kaaproject.kaa.server.transport.custom.config.CustomConfig;
 
public class CustomTransport extends AbstractKaaTransport<CustomConfig>{
 
    /**
     * Initialize a transport instance with a particular configuration and
     * common transport properties that are accessible via the context. The configuration is an Avro
     * object. The serializaion/deserialization is done using the schema specified in
     * {@link KaaTransportConfig}.
     *
     * @param context
     *            the transport initialization context
     * @throws TransportLifecycleException
     */
    @Override
    protected void init(SpecificTransportContext<CustomConfig> context) throws TransportLifecycleException {
        // TODO Auto-generated method stub
    }
 
    /**
     * Retrieves the serialized connection data. This data will be used in an
     * endpoint sdk to set up a connection to this transport instance.
     * Used to provide implementation of {@link Transport#getConnectionInfo()}.
     * 
     * @return the serialized connection data
     */
    @Override
    protected ByteBuffer getSerializedConnectionInfo() {
        // TODO Auto-generated method stub
        return null;
    }
 
    /**
     * Starts a transport instance. This method should block its caller thread
     * until the transport is started. This method should not block its caller
     * thread after the startup sequence is successfully completed.
     */
    @Override
    public void start() {
        // TODO Auto-generated method stub
    }
 
    /**
     * Stops the transport instance. This method should block its current thread
     * until the transport is stopped. The transport may be started again after it is
     * stopped.
     */
    @Override
    public void stop() {
        // TODO Auto-generated method stub
    }
 
    /**
     * Returns a min version of the transport protocol that is supported by this transport.
     * Useful when a single transport instance needs to support multiple versions of the client protocol implementations.
     */
    @Override
    protected int getMinSupportedVersion() {
        // TODO Auto-generated method stub
        return 1;
    }
 
    /**
     * Returns a max version of the transport protocol that is supported by this transport.
     * Useful when a single transport instance needs to support multiple versions of the client protocol implementations.
     */
    @Override
    protected int getMaxSupportedVersion() {
        // TODO Auto-generated method stub
        return 1;
    }
 
    @Override
    public Class<CustomConfig> getConfigurationClass() {
        // TODO Auto-generated method stub
        return CustomConfig.class;
    }
}

Transport provisioning

To provision the implemented transport, you need to put all the transport related classes into the classpath of the server. Also, you need to make sure that the transport configuration file is present in the classpath and its schema and name match appropriate parameters from your transport descriptor.

The following example illustrates the configuration file contents that match our transport. This file should be named custom-transport.config.

{
"host":"${transport.bindInterface}",
"port":9997
}

Note: you can use transport configuration variables from the operations-server.properties or bootstrap-server.properties files; these variables must have the transport prefix.


Copyright © 2014-2015, CyberVision, Inc.

  • No labels