001/*
002 * #%L
003 * Netarchivesuite - common
004 * %%
005 * Copyright (C) 2005 - 2014 The Royal Danish Library, the Danish State and University Library,
006 *             the National Library of France and the Austrian National Library.
007 * %%
008 * This program is free software: you can redistribute it and/or modify
009 * it under the terms of the GNU Lesser General Public License as
010 * published by the Free Software Foundation, either version 2.1 of the
011 * License, or (at your option) any later version.
012 * 
013 * This program is distributed in the hope that it will be useful,
014 * but WITHOUT ANY WARRANTY; without even the implied warranty of
015 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
016 * GNU General Lesser Public License for more details.
017 * 
018 * You should have received a copy of the GNU General Lesser Public
019 * License along with this program.  If not, see
020 * <http://www.gnu.org/licenses/lgpl-2.1.html>.
021 * #L%
022 */
023package dk.netarkivet.common.utils;
024
025import java.util.List;
026import java.util.Map;
027
028import dk.netarkivet.common.exceptions.ArgumentNotValid;
029import dk.netarkivet.common.exceptions.IllegalState;
030
031/**
032 * An interface defining a structure with nodes, subnodes and leaves. This is a recursively defined datastructure, so
033 * each instance can be a tree or a leaf. Each is node is named with a String, and each leaf can contain a value of type
034 * T. Each non-leaf tree can have any number of subnodes, each identified by a String.
035 *
036 * @param <T> The leaf type
037 */
038public interface StringTree<T> {
039
040    /**
041     * Returns true if this object is a leaf, and thus if getValue is legal.
042     *
043     * @return True if the implementing object is a leaf, false otherwise.
044     */
045    boolean isLeaf();
046
047    /**
048     * Get the value of a named sub-leaf.
049     *
050     * @param name Name of the sub-leaf to get the value of. These are strings, and as a shorthand may specify subtrees
051     * of subtrees by separating each level with '.', i.e. getSubtrees("subtree.subsubtree").
052     * @return The value of the named leaf of this Tree, if it exists.
053     * @throws IllegalState if this StringTree does not have exactly one leaf sub-node with the given name.
054     * @throws ArgumentNotValid if argument is null or empty.
055     */
056    T getValue(String name);
057
058    /**
059     * Get the value of a leaf.
060     *
061     * @return The value of this Tree, if it is a leaf.
062     * @throws IllegalState if this StringTree is a node.
063     */
064    T getValue();
065
066    /**
067     * Get the only subtree with the given name.
068     *
069     * @param name The name of the subtree. These are strings, and as a shorthand may specify subtrees of subtrees by
070     * separating each level with '.', i.e. getSubtrees("subtree.subsubtree").
071     * @return The single subtree with the given name.
072     * @throws IllegalState if this object is a leaf or if there is not exactly one subtree with the given name.
073     * @throws ArgumentNotValid if argument is null or empty.
074     */
075    StringTree<T> getSubTree(String name);
076
077    /**
078     * Get the named subtrees.
079     *
080     * @param name The name of the subtrees. These are strings, and as a shorthand may specify subtrees of subtrees by
081     * separating each level with '.', i.e. getSubtrees("subtree.subsubtree").
082     * @return All subtrees with the given name, or an empty list for none.
083     * @throws IllegalState if this object is a leaf.
084     * @throws ArgumentNotValid if argument is null or empty.
085     */
086    List<StringTree<T>> getSubTrees(String name);
087
088    /**
089     * Get a map of all direct children of this node.
090     *
091     * @return Map of children of this node, or an empty map for none.
092     * @throws IllegalState if this object is a leaf.
093     */
094    Map<String, List<StringTree<T>>> getChildMultimap();
095
096    /**
097     * Get a map of all direct subtrees, assuming that all subtrees are uniquely named.
098     *
099     * @return Map of all subtrees.
100     * @throws IllegalState if this object is a leaf or if there is more than one subtree with the same name.
101     */
102    Map<String, StringTree<T>> getChildMap();
103
104    /**
105     * Get a multimap of the names and values of all direct subtrees, assuming that all subtrees are leafs.
106     *
107     * @return Multimap from subtree names to values of their leaves.
108     * @throws IllegalState if this object is a leaf or if any of its children are not leaves.
109     */
110    Map<String, List<T>> getLeafMultimap();
111
112    /**
113     * Get a map of the names and values of all subtrees, assuming that all subtrees are leafs and are uniquely named.
114     *
115     * @return Map from subtree names to values of their leaves.
116     * @throws IllegalState if this object is a leaf or if the subtrees are not uniquely named, or if any of its
117     * children are not leaves.
118     */
119    Map<String, T> getLeafMap();
120
121}