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}