org.modeshape.schematic.SchematicDb Maven / Gradle / Ivy
Show all versions of modeshape-schematic Show documentation
/*
* ModeShape (http://www.modeshape.org)
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package org.modeshape.schematic;
import java.util.Collection;
import java.util.List;
import org.modeshape.schematic.annotation.RequiresTransaction;
import org.modeshape.schematic.document.Document;
import org.modeshape.schematic.document.EditableDocument;
/**
* A store for JSON documents and other binary content, plus a library of JSON Schema documents used to describe and validate the
* stored documents.
*
* @author Horia Chiorean
* @since 5.0
*/
public interface SchematicDb extends TransactionListener, Lifecycle, Lockable {
/**
* Returns a unique identifier for this schematic DB.
*
* Implementations should make sure that the provided id is unique per storage instance.
* In other words, if two {@link SchematicDb} instances of the same type store data in two different places, they should
* return a different id.
*
*
* @return a {@link String}, never {@code null}
*/
String id();
/**
* Returns a set over all the keys present in the DB.
*
* If this method is called within an existing transaction, it should take into account the transient transactional context
* (i.e. any local but not yet committed changes)
*
*
* @return a {@link List} instance, never {@code null}
*/
List keys();
/**
* Get the document with the supplied key. This will represent the full {@link SchematicEntry} document if one exists.
*
* If this method is called within an existing transaction, it should take into account the transient transactional context
* (i.e. any local but not yet committed changes)
*
*
* @param key the key or identifier for the document
* @return the document, or null if there was no document with the supplied key
*/
Document get( String key );
/**
* Loads a set of documents from the DB returning the corresponding schematic entries.
*
*
* If this method is called within an existing transaction, it should take into account the transient transactional
* context (i.e. any local but not yet committed changes) and either use that (if it exists) or the persisted information.
*
*
* @param keys an {@link Collection} of keys; never {@code null}
* @return a {@link List} of {@link SchematicEntry entries}; never {@code null}
*/
List load(Collection keys);
/**
* Stores the supplied schematic entry under the given key. If an entry already exists with the same key, it should be
* overwritten.
* @param key a schematic entry id, never {@code null}
* @param entry a {@link SchematicEntry} instance, never {@code null}
*/
@RequiresTransaction
void put(String key, SchematicEntry entry);
/**
* Get an editor for the content of the given entry with the supplied key.
*
* @param key the key or identifier for the document
* @param createIfMissing true if a new entry should be created and added to the database if an existing entry does not exist
* @return the content document, or null if there was no document with the supplied key and a new one could not be created
*/
@RequiresTransaction
EditableDocument editContent(String key, boolean createIfMissing);
/**
* Store the supplied content at the given key.
*
*
* Depending on the actual implementation, this may or may not be thread-safe. ModeShape never assumes this is thread-safe
* when calling it.
*
*
* @param key the key or identifier for the content
* @param content the content that is to be stored
* @return the existing entry for the supplied key, or null if there was no entry and the put was successful
*/
@RequiresTransaction
SchematicEntry putIfAbsent(String key, Document content);
/**
* Remove the existing document at the given key.
*
* @param key the key or identifier for the document
* @return {@code true} if the removal was successful, {@code false} otherwise
*/
@RequiresTransaction
boolean remove(String key);
/**
* Removes all the entries from this DB.
*/
@RequiresTransaction
void removeAll();
/**
* Store the supplied content document at the given key. If a document already exists with the given key, this should
* overwrite the existing document.
*
* @param key the key or identifier for the document
* @param content the document that is to be stored
* @see #putIfAbsent(String, Document)
*/
@RequiresTransaction
default void put( String key, Document content ) {
put(key, SchematicEntry.create(key, content));
}
@Override
@RequiresTransaction
default boolean lockForWriting( List locks ) {
throw new UnsupportedOperationException(getClass() + " does not support exclusive locking");
}
/**
* Get the entry with the supplied key.
*
* If this method is called within an existing transaction, it should take into account the transient transactional context
* (i.e. any local but not yet committed changes)
*
*
* @param key the key or identifier for the document
* @return the entry, or null if there was no document with the supplied key
*/
default SchematicEntry getEntry( String key) {
Document doc = get(key);
return doc != null ? () -> doc : null;
}
/**
* Determine whether the database contains an entry with the supplied key.
*
* If this method is called within an existing transaction, it should take into account the transient transactional context
* (i.e. any local but not yet committed changes)
*
*
* @param key the key or identifier for the document
* @return true if the database contains an entry with this key, or false otherwise
*/
default boolean containsKey( String key ) {
return get(key) != null;
}
/**
* Store the supplied document. This document is expected to be a full entry document, which contains both a "metadata"
* and "content" section.
*
* @param entryDocument the document that contains the metadata document and content document.
* @see #putIfAbsent(String, Document)
*/
@RequiresTransaction
default void putEntry(Document entryDocument) {
SchematicEntry entry = SchematicEntry.fromDocument(entryDocument);
put(entry.id(), entry);
}
}