112 lines
4.2 KiB
Java
112 lines
4.2 KiB
Java
/*******************************************************************************
|
|
* Copyright (c) 2009, 2014 IBM Corp.
|
|
*
|
|
* All rights reserved. This program and the accompanying materials
|
|
* are made available under the terms of the Eclipse Public License v2.0
|
|
* and Eclipse Distribution License v1.0 which accompany this distribution.
|
|
*
|
|
* The Eclipse Public License is available at
|
|
* https://www.eclipse.org/legal/epl-2.0
|
|
* and the Eclipse Distribution License is available at
|
|
* https://www.eclipse.org/org/documents/edl-v10.php
|
|
*
|
|
* Contributors:
|
|
* Dave Locke - initial API and implementation and/or initial documentation
|
|
*/
|
|
package org.eclipse.paho.mqttv5.common;
|
|
|
|
/**
|
|
* Represents an object used to pass data to be persisted across the
|
|
* <code>MqttClientPersistence</code> interface.
|
|
* <p>
|
|
* When data is passed across the interface the header and payload are
|
|
* separated, so that unnecessary message copies may be avoided. For example, if
|
|
* a 10 MB payload was published it would be inefficient to create a byte array
|
|
* a few bytes larger than 10 MB and copy the MQTT message header and payload
|
|
* into a contiguous byte array.
|
|
* </p>
|
|
* <p>
|
|
* When the request to persist data is made a separate byte array and offset is
|
|
* passed for the header and payload. Only the data between offset and length
|
|
* need be persisted. So for example, a message to be persisted consists of a
|
|
* header byte array starting at offset 1 and length 4, plus a payload byte
|
|
* array starting at offset 30 and length 40000. There are three ways in which
|
|
* the persistence implementation may return data to the client on recovery:
|
|
* </p>
|
|
* <ul>
|
|
* <li>It could return the data as it was passed in originally, with the same
|
|
* byte arrays and offsets.</li>
|
|
* <li>It could safely just persist and return the bytes from the offset for the
|
|
* specified length. For example, return a header byte array with offset 0 and
|
|
* length 4, plus a payload byte array with offset 0 and length 40000</li>
|
|
* <li>It could return the header and payload as a contiguous byte array with
|
|
* the header bytes preceeding the payload. The contiguous byte array should be
|
|
* set as the header byte array, with the payload byte array being null. For
|
|
* example, return a single byte array with offset 0 and length 40004. This is
|
|
* useful when recovering from a file where the header and payload could be
|
|
* written as a contiguous stream of bytes.</li>
|
|
* </ul>
|
|
*/
|
|
public interface MqttPersistable {
|
|
|
|
/**
|
|
* Returns the header bytes in an array. The bytes start at
|
|
* {@link #getHeaderOffset()} and continue for {@link #getHeaderLength()}.
|
|
*
|
|
* @return the header bytes.
|
|
* @throws MqttPersistenceException
|
|
* if an error occurs getting the Header Bytes
|
|
*/
|
|
byte[] getHeaderBytes() throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Returns the length of the header.
|
|
*
|
|
* @return the header length
|
|
* @throws MqttPersistenceException
|
|
* if an error occurs getting the Header length
|
|
*/
|
|
int getHeaderLength() throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Returns the offset of the header within the byte array returned by
|
|
* {@link #getHeaderBytes()}.
|
|
*
|
|
* @return the header offset.
|
|
* @throws MqttPersistenceException
|
|
* if an error occurs getting the Header offset
|
|
*
|
|
*/
|
|
int getHeaderOffset() throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Returns the payload bytes in an array. The bytes start at
|
|
* {@link #getPayloadOffset()} and continue for {@link #getPayloadLength()}.
|
|
*
|
|
* @return the payload bytes.
|
|
* @throws MqttPersistenceException
|
|
* if an error occurs getting the Payload Bytes
|
|
*/
|
|
byte[] getPayloadBytes() throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Returns the length of the payload.
|
|
*
|
|
* @return the payload length.
|
|
* @throws MqttPersistenceException
|
|
* if an error occurs getting the Payload length
|
|
*/
|
|
int getPayloadLength() throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Returns the offset of the payload within the byte array returned by
|
|
* {@link #getPayloadBytes()}.
|
|
*
|
|
* @return the payload offset.
|
|
* @throws MqttPersistenceException
|
|
* if an error occurs getting the Payload Offset
|
|
*
|
|
*/
|
|
int getPayloadOffset() throws MqttPersistenceException;
|
|
}
|