X-Git-Url: https://git.pterodactylus.net/?a=blobdiff_plain;f=src%2Fmain%2Fjava%2Fnet%2Fpterodactylus%2Fsone%2Fdatabase%2FDatabase.java;fp=src%2Fmain%2Fjava%2Fnet%2Fpterodactylus%2Fsone%2Fdatabase%2FDatabase.java;h=7b481519999b608173985af40fa6a1065751672a;hb=e0ffa7c1d773690b0d6c24b4d455c79dbd4e6eca;hp=0000000000000000000000000000000000000000;hpb=f744cc1bff979d9f493b116cf5ad40b603065be7;p=Sone.git diff --git a/src/main/java/net/pterodactylus/sone/database/Database.java b/src/main/java/net/pterodactylus/sone/database/Database.java new file mode 100644 index 0000000..7b48151 --- /dev/null +++ b/src/main/java/net/pterodactylus/sone/database/Database.java @@ -0,0 +1,197 @@ +/* + * Sone - Database.java - Copyright © 2011 David Roden + * + * This program is free software: you can redistribute it and/or modify + * it under the terms of the GNU General Public License as published by + * the Free Software Foundation, either version 3 of the License, or + * (at your option) any later version. + * + * This program is distributed in the hope that it will be useful, + * but WITHOUT ANY WARRANTY; without even the implied warranty of + * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + * GNU General Public License for more details. + * + * You should have received a copy of the GNU General Public License + * along with this program. If not, see . + */ + +package net.pterodactylus.sone.database; + +import java.util.Collection; + +import net.pterodactylus.sone.data.Sone; + +/** + * Interface for Sone’s database. + * + * @author David ‘Bombe’ Roden + */ +public interface Database { + + /** + * Returns whether the given Sone is a local Sone. + * + * @param sone + * The Sone to check + * @return {@code true} if the given Sone is a local Sone, {@code false} + * otherwise + * @throws IllegalArgumentException + * if {@code sone} is {@code null} + * @throws DatabaseException + * if a database error occurs + */ + public boolean isLocalSone(Sone sone) throws DatabaseException; + + /** + * Returns whether the given Sone ID belongs to a local Sone. + * + * @param id + * The Sone ID to check + * @return {@code true} if the given Sone ID belongs to a local Sone, + * {@code false} otherwise + * @throws IllegalArgumentException + * if {@code id} is {@code null} + * @throws DatabaseException + * if a database error occurs + */ + public boolean isLocalSone(String id) throws DatabaseException; + + /** + * Returns whether the given Sone is a remote Sone. + * + * @param sone + * The Sone to check + * @return {@code true} if the given Sone is a remote Sone, {@code false} + * otherwise + * @throws IllegalArgumentException + * if {@code sone} is {@code null} + * @throws DatabaseException + * if a database error occurs + */ + public boolean isRemoteSone(Sone sone) throws DatabaseException; + + /** + * Returns whether the given Sone ID belongs to a remote Sone. + * + * @param id + * The Sone ID to check + * @return {@code true} if the given Sone ID belongs to a remote Sone, + * {@code false} otherwise + * @throws IllegalArgumentException + * if {@code id} is {@code null} + * @throws DatabaseException + * if a database error occurs + */ + public boolean isRemoteSone(String id) throws DatabaseException; + + /** + * Returns the Sone with the given ID, creating a new Sone if a Sone with + * the given ID does not exist and {@code create} is {@code true}. When + * searching for a Sone with the given IDs, local Sones are preferred. + * + * @param id + * The ID of the new Sone + * @param create + * {@code true} to create a new Sone if a Sone with the given ID + * does not exist, {@code false} to return {@code null} if a Sone + * with the given ID does not exist + * @return The created Sone + * @throws IllegalArgumentException + * if {@code id} is {@code null} + * @throws DatabaseException + * if a database error occurs + */ + public Sone getSone(String id, boolean create) throws DatabaseException; + + /** + * Returns all known Sones. + * + * @return All known Sones + * @throws DatabaseException + * if a database error occurs + */ + public Collection getSones() throws DatabaseException; + + /** + * Returns all known local Sones. + * + * @return All known local Sones + * @throws DatabaseException + * if a database error occurs + */ + public Collection getLocalSones() throws DatabaseException; + + /** + * Returns all known remote Sones. + * + * @return All known remote Sones + * @throws DatabaseException + * if a database error occurs + */ + public Collection getRemoteSones() throws DatabaseException; + + /** + * Returns the local Sone with the given ID, creating it if it doesn’t exist + * and {@code create} is {@code true}. + * + * @param id + * The ID of the Sone + * @param create + * {@code true} to create a Sone if no Sone with the given ID + * exists yet, {@code false} to return {@code null} + * @return The existing Sone, the created Sone, or {@code null} + * @throws DatabaseException + * if adatabase error occurs + */ + public Sone getLocalSone(String id, boolean create) throws DatabaseException; + + /** + * Returns the remote Sone with the given ID, creating it if it doesn’t + * exist and {@code create} is {@code true}. + * + * @param id + * The ID of the Sone + * @param create + * {@code true} to create a Sone if no Sone with the given ID + * exists yet, {@code false} to return {@code null} + * @return The existing Sone, the created Sone, or {@code null} + * @throws DatabaseException + * if adatabase error occurs + */ + public Sone getRemoteSone(String id, boolean create) throws DatabaseException; + + /** + * Stores the given Sone. The given Sone has to be an object that was + * returned by a previous call to {@link #getSone(String, boolean)}. + * + * @param sone + * The Sone to store + * @throws IllegalArgumentException + * if {@code sone} is {@code null}, or the Sone was not + * retrieved by a call to {@link #getSone(String, boolean)} + * @throws DatabaseException + * if a database error occurs + */ + public void saveSone(Sone sone) throws DatabaseException; + + /** + * Removes the given Sone from the database. + * + * @param sone + * The Sone to remove + * @throws DatabaseException + * if a database error occurs + */ + public void removeSone(Sone sone) throws DatabaseException; + + /** + * Removes the Sone with the given ID from the database. + * + * @param id + * The ID of the Sone to remove + * @throws DatabaseException + * if a database error occurs + */ + public void removeSone(String id) throws DatabaseException; + +}