105 lines
4.6 KiB
Java
105 lines
4.6 KiB
Java
/*******************************************************************************
|
|
* Copyright (c) 2009, 2019 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.client;
|
|
|
|
import java.util.Enumeration;
|
|
|
|
import org.eclipse.paho.mqttv5.common.MqttPersistable;
|
|
import org.eclipse.paho.mqttv5.common.MqttPersistenceException;
|
|
|
|
/**
|
|
* Represents a persistent data store, used to store outbound and inbound messages while they
|
|
* are in flight, enabling delivery to the QoS specified. You can specify an implementation
|
|
* of this interface using {@link MqttClient#MqttClient(String, String, MqttClientPersistence)},
|
|
* which the {@link MqttClient} will use to persist QoS 1 and 2 messages.
|
|
* <p>
|
|
* If the methods defined throw the MqttPersistenceException then the state of the data persisted
|
|
* should remain as prior to the method being called. For example, if {@link #put(String, MqttPersistable)}
|
|
* throws an exception at any point then the data will be assumed to not be in the persistent store.
|
|
* Similarly if {@link #remove(String)} throws an exception then the data will be
|
|
* assumed to still be held in the persistent store.</p>
|
|
* <p>
|
|
* It is up to the persistence interface to log any exceptions or error information
|
|
* which may be required when diagnosing a persistence failure.</p>
|
|
*/
|
|
public interface MqttClientPersistence {
|
|
/**
|
|
* Initialise the persistent store.
|
|
* If a persistent store exists for this client ID then open it, otherwise
|
|
* create a new one. If the persistent store is already open then just return.
|
|
* An application may use the same client ID to connect to many different
|
|
* servers, so the client ID in conjunction with the
|
|
* connection will uniquely identify the persistence store required.
|
|
*
|
|
* @param clientId The client for which the persistent store should be opened.
|
|
* @throws MqttPersistenceException if there was a problem opening the persistent store.
|
|
*/
|
|
void open(String clientId) throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Close the persistent store that was previously opened.
|
|
* This will be called when a client application disconnects from the broker.
|
|
* @throws MqttPersistenceException if an error occurs closing the persistence store.
|
|
*/
|
|
void close() throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Puts the specified data into the persistent store.
|
|
* @param key the key for the data, which will be used later to retrieve it.
|
|
* @param persistable the data to persist
|
|
* @throws MqttPersistenceException if there was a problem putting the data
|
|
* into the persistent store.
|
|
*/
|
|
void put(String key, MqttPersistable persistable) throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Gets the specified data out of the persistent store.
|
|
* @param key the key for the data, which was used when originally saving it.
|
|
* @return the un-persisted data
|
|
* @throws MqttPersistenceException if there was a problem getting the data
|
|
* from the persistent store.
|
|
*/
|
|
MqttPersistable get(String key) throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Remove the data for the specified key.
|
|
* @param key The key for the data to remove
|
|
* @throws MqttPersistenceException if there was a problem removing the data.
|
|
*/
|
|
void remove(String key) throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Returns an Enumeration over the keys in this persistent data store.
|
|
* @return an enumeration of {@link String} objects.
|
|
* @throws MqttPersistenceException if there was a problem getting they keys
|
|
*/
|
|
Enumeration<String> keys() throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Clears persistence, so that it no longer contains any persisted data.
|
|
* @throws MqttPersistenceException if there was a problem clearing all data from the persistence store
|
|
*/
|
|
void clear() throws MqttPersistenceException;
|
|
|
|
/**
|
|
* Returns whether or not data is persisted using the specified key.
|
|
* @param key the key for data, which was used when originally saving it.
|
|
* @return True if the persistence store contains the key
|
|
* @throws MqttPersistenceException if there was a problem checking whether they key existed.
|
|
*/
|
|
boolean containsKey(String key) throws MqttPersistenceException;
|
|
}
|