org.eclipse.paho.mqttv5.client.MqttClientPersistence Maven / Gradle / Ivy
The newest version!
/*******************************************************************************
* 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.
*
* 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.
*
* It is up to the persistence interface to log any exceptions or error information
* which may be required when diagnosing a persistence failure.
*/
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 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;
}
© 2015 - 2024 Weber Informatics LLC | Privacy Policy