org.eclipse.leshan.server.LwM2mServer Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of leshan-all Show documentation
A LWM2M client and server based on Californium (CoAP) all in one.
The newest version!
/*******************************************************************************
 * Copyright (c) 2013-2015 Sierra Wireless and others.
 * 
 * All rights reserved. This program and the accompanying materials
 * are made available under the terms of the Eclipse Public License v1.0
 * and Eclipse Distribution License v1.0 which accompany this distribution.
 * 
 * The Eclipse Public License is available at
 *    http://www.eclipse.org/legal/epl-v10.html
 * and the Eclipse Distribution License is available at
 *    http://www.eclipse.org/org/documents/edl-v10.html.
 * 
 * Contributors:
 *     Sierra Wireless - initial API and implementation
 *******************************************************************************/
package org.eclipse.leshan.server;

import org.eclipse.leshan.core.node.codec.CodecException;
import org.eclipse.leshan.core.request.DownlinkRequest;
import org.eclipse.leshan.core.request.exception.ClientSleepingException;
import org.eclipse.leshan.core.request.exception.InvalidResponseException;
import org.eclipse.leshan.core.request.exception.RequestCanceledException;
import org.eclipse.leshan.core.request.exception.RequestRejectedException;
import org.eclipse.leshan.core.request.exception.TimeoutException;
import org.eclipse.leshan.core.response.ErrorCallback;
import org.eclipse.leshan.core.response.LwM2mResponse;
import org.eclipse.leshan.core.response.ResponseCallback;
import org.eclipse.leshan.server.model.LwM2mModelProvider;
import org.eclipse.leshan.server.observation.ObservationService;
import org.eclipse.leshan.server.queue.PresenceListener;
import org.eclipse.leshan.server.queue.PresenceService;
import org.eclipse.leshan.server.registration.Registration;
import org.eclipse.leshan.server.registration.RegistrationService;
import org.eclipse.leshan.server.security.SecurityStore;

/**
 * An OMA Lightweight M2M device management server.
 *
 * Will receive client registration through the "/rd" resource. Is able to send requests (Read, Write, Create, Delete,
 * Execute, Discover, Observer) to specified clients.
 *
 * It's your main entry point for using the Leshan-core API.
 */
public interface LwM2mServer {

    /**
     * Starts the server (bind port, start to listen CoAP messages).
     */
    void start();

    /**
     * Stops the server, i.e. unbinds it from all ports. Frees as much system resources as possible to still be able to
     * be started.
     */
    void stop();

    /**
     * Destroys the server, i.e. unbinds from all ports and frees all system resources.
     */
    void destroy();

    /**
     * Sends a Lightweight M2M request synchronously. Will block until a response is received from the remote client.
     * 
     * @param destination the remote client
     * @param request the request to the client
     * @return the response or null if the CoAP timeout expires ( see
     *         http://tools.ietf.org/html/rfc7252#section-4.2 ).
     * 
     * @throws CodecException if request payload can not be encoded.
     * @throws InterruptedException if the thread was interrupted.
     * @throws RequestRejectedException if the request is rejected by foreign peer.
     * @throws RequestCanceledException if the request is cancelled.
     * @throws InvalidResponseException if the response received is malformed.
     * @throws ClientSleepingException if the client is sleeping and then the request cannot be sent. This exception
     *         will never be raised if Queue Mode support is deactivate.
     */
     T send(Registration destination, DownlinkRequest request)
            throws InterruptedException, CodecException, InvalidResponseException, RequestCanceledException,
            RequestRejectedException, ClientSleepingException;

    /**
     * Sends a Lightweight M2M request synchronously. Will block until a response is received from the remote client.
     * 
     * @param destination the remote client
     * @param request the request to send to the client
     * @param timeout the request timeout in millisecond
     * @return the response or null if the timeout expires (given parameter or CoAP timeout).
     * 
     * @throws CodecException if request payload can not be encoded.
     * @throws InterruptedException if the thread was interrupted.
     * @throws RequestRejectedException if the request is rejected by foreign peer.
     * @throws RequestCanceledException if the request is cancelled.
     * @throws InvalidResponseException if the response received is malformed.
     * @throws ClientSleepingException if the client is sleeping and then the request cannot be sent. This exception
     *         will never be raised if Queue Mode support is deactivate.
     */
     T send(Registration destination, DownlinkRequest request, long timeout)
            throws InterruptedException, CodecException, InvalidResponseException, RequestCanceledException,
            RequestRejectedException, ClientSleepingException;

    /**
     * Sends a Lightweight M2M request asynchronously.
     * 
     * @param destination the remote client
     * @param request the request to send to the client
     * @param responseCallback a callback called when a response is received (successful or error response)
     * @param errorCallback a callback called when an error or exception occurred when response is received. It can be :
     *        
     *        {@link RequestRejectedException} if the request is rejected by foreign peer.
     *        {@link RequestCanceledException} if the request is cancelled.
     *        {@link InvalidResponseException} if the response received is malformed.
     *        {@link TimeoutException} if the CoAP timeout expires ( see
     *        http://tools.ietf.org/html/rfc7252#section-4.2 ).
     *        or any other RuntimeException for unexpected issue.
     *        
     * @throws CodecException if request payload can not be encoded.
     * @throws ClientSleepingException if the client is sleeping and then the request cannot be sent. This exception
     *         will never be raised if Queue Mode support is deactivate.
     */
     void send(Registration destination, DownlinkRequest request,
            ResponseCallback responseCallback, ErrorCallback errorCallback)
            throws CodecException, ClientSleepingException;

    /**
     * Sends a Lightweight M2M request asynchronously.
     * 
     * @param destination the remote client
     * @param request the request to send to the client
     * @param timeout the request timeout in millisecond
     * @param responseCallback a callback called when a response is received (successful or error response)
     * @param errorCallback a callback called when an error or exception occurred when response is received. It can be :
     *        
     *        {@link RequestRejectedException} if the request is rejected by foreign peer.
     *        {@link RequestCanceledException} if the request is cancelled.
     *        {@link InvalidResponseException} if the response received is malformed.
     *        {@link TimeoutException} if the CoAP timeout expires ( see
     *        http://tools.ietf.org/html/rfc7252#section-4.2 ).
     *        or any other RuntimeException for unexpected issue.
     *        
     * @throws CodecException if request payload can not be encoded.
     * @throws ClientSleepingException if the client is sleeping and then the request cannot be sent. This exception
     *         will never be raised if Queue Mode support is deactivate.
     */
     void send(Registration destination, DownlinkRequest request, long timeout,
            ResponseCallback responseCallback, ErrorCallback errorCallback)
            throws CodecException, ClientSleepingException;

    /**
     * Get the registration service to access to registered clients. You can use this object for listening client
     * registration lifecycle.
     */
    RegistrationService getRegistrationService();

    /**
     * Get the Observation service to access current observations. You can use this object for listening resource
     * observation or cancel it.
     */
    ObservationService getObservationService();

    /**
     * Get the Presence service to get the status of LWM2M clients connected with binding mode 'Q'. You can use this
     * object to add {@link PresenceListener} to get notified when a device comes online or offline.
     */
    PresenceService getPresenceService();

    /**
     * Get the SecurityStore containing of security information.
     */
    SecurityStore getSecurityStore();

    /**
     * Get the provider in charge of retrieving the object definitions for each client.
     */
    LwM2mModelProvider getModelProvider();

}