001package com.hfg.xml;
002
003
004import com.hfg.util.Recursion;
005
006import java.util.Collection;
007import java.util.List;
008
009//------------------------------------------------------------------------------
010/**
011 Interface for an unusual XML object that may have content or subtags but not a name or attributes
012 (for example an IE conditional comment in HTML). Such objects are not true XML tags but
013 this can be a useful abstraction for constructing HTML.
014
015 @author J. Alex Taylor, hairyfatguy.com
016 */
017//------------------------------------------------------------------------------
018// com.hfg XML/HTML Coding Library
019//
020// This library is free software; you can redistribute it and/or
021// modify it under the terms of the GNU Lesser General Public
022// License as published by the Free Software Foundation; either
023// version 2.1 of the License, or (at your option) any later version.
024//
025// This library is distributed in the hope that it will be useful,
026// but WITHOUT ANY WARRANTY; without even the implied warranty of
027// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
028// Lesser General Public License for more details.
029//
030// You should have received a copy of the GNU Lesser General Public
031// License along with this library; if not, write to the Free Software
032// Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
033//
034// J. Alex Taylor, President, Founder, CEO, COO, CFO, OOPS hairyfatguy.com
035// jataylor@hairyfatguy.com
036//------------------------------------------------------------------------------
037
038public interface XMLContainer extends XMLizable
039{
040
041   //---------------------------------------------------------------------------
042   public boolean hasContent();
043
044
045   //---------------------------------------------------------------------------
046   public XMLContainer setContent(CharSequence inContent);
047
048   //---------------------------------------------------------------------------
049   /**
050    Clears content (not subtags).
051    */
052   public void clearContent();
053
054   //---------------------------------------------------------------------------
055   public XMLContainer addContent(CharSequence inContent);
056
057   //---------------------------------------------------------------------------
058   public XMLContainer addContentWithoutEscaping(CharSequence inContent);
059
060   //---------------------------------------------------------------------------
061   /**
062    The returned content does not contain any embedded subtags.
063    @return the XML tag's content stripped of any subtags
064    */
065   public String getContent();
066
067   //----------------------------------------------------------------------------
068   /**
069    Expands character entities before retuning the content of this XMLTag.
070    The returned content does not contain any embedded subtags.
071    @return the XML tag's unescaped content stripped of any subtags
072    */
073   public String getUnescapedContent();
074
075
076   //---------------------------------------------------------------------------
077   public void addSubtag(XMLizable inSubtag);
078
079   //---------------------------------------------------------------------------
080   /**
081    @param inSubtags Collection that should only contain XMLNode objects.
082    */
083   public void addSubtags(Collection<? extends XMLizable> inSubtags);
084
085   //---------------------------------------------------------------------------
086   /**
087    Sets the subtags of this object to those specified.
088    @param inSubtags the list of subtags to be added to this XML tag
089    */
090   public <T extends XMLizable> void setSubtags(List<T> inSubtags);
091
092   //---------------------------------------------------------------------------
093   /**
094    Returns a List of all subtags on this object.
095    @return the list of subtags (inclusive of XML comments)
096    */
097   public <T extends XMLizable> List<T> getSubtags();
098
099   //---------------------------------------------------------------------------
100   /**
101    Returns a List of all subtags on this object that implement XMLNode.
102    Useful as a way to avoid XML comments, etc.
103    @return the list of subtags (exclusive of XML comments)
104    */
105   public <T extends XMLNode> List<T> getXMLNodeSubtags();
106
107
108   //---------------------------------------------------------------------------
109   /**
110    Removes all instances of the specified subtag from this object.
111    @param inSubtag the subtag to be removed
112    */
113   public void removeSubtag(XMLizable inSubtag);
114
115   //---------------------------------------------------------------------------
116   /**
117    Removes all subtags from this object.
118    */
119   public void clearSubtags();
120
121   //---------------------------------------------------------------------------
122   /**
123    Returns the index of the specified subtag.
124    @param inSubtag the subtag for which to determine the index
125    @return the index of the specified subtag or -1 if this tag does not contain the specified subtag.
126    */
127   public int indexOf(XMLizable inSubtag);
128
129   //---------------------------------------------------------------------------
130   /**
131    Returns the subtag of the specified tag name.
132    @param inTagName the name of the required subtag
133    @return the subtag with the specified name
134    @throws XMLException if zero or more than one subtag with the specified tag name is found.
135    */
136   public <T extends XMLNode> T getRequiredSubtagByName(String inTagName);
137
138   //---------------------------------------------------------------------------
139   /**
140    Returns the subtag of the specified tag name.
141    @param inTagName the name of the required subtag
142    @return the subtag with the specified name
143    @throws XMLException if zero or more than one subtag with the specified tag name is found.
144    */
145   public <T extends XMLNode> T getRequiredSubtagByName(XMLName inTagName);
146
147   //---------------------------------------------------------------------------
148   /**
149    Returns the subtag of the specified tag name.
150    @param inTagName the name of the optional subtag
151    @return the subtag with the specified name
152    @throws XMLException if more than one subtag with the specified tag name is found.
153    */
154   public <T extends XMLNode> T getOptionalSubtagByName(String inTagName);
155
156   //---------------------------------------------------------------------------
157   /**
158    Returns the subtag of the specified tag name.
159    @param inTagName the name of the optional subtag
160    @return the subtag with the specified name
161    @throws XMLException if more than one subtag with the specified tag name is found.
162    */
163   public <T extends XMLNode> T getOptionalSubtagByName(XMLName inTagName);
164
165   //---------------------------------------------------------------------------
166   /**
167    Returns a List of all subtags with the specified tag name on this XMLTag object.
168    @param inTagName the name of the requested subtags
169    @return the list of requested subtags
170    */
171   public <T extends XMLNode> List<T> getSubtagsByName(String inTagName);
172
173   //---------------------------------------------------------------------------
174   /**
175    Returns a List of all subtags with the specified tag name on this XMLTag object.
176    @param inTagName the name of the requested subtags
177    @return the list of requested subtags
178    */
179   public <T extends XMLNode> List<T> getSubtagsByName(XMLName inTagName);
180
181   //---------------------------------------------------------------------------
182   /**
183    Returns a List of all subtags with the specified tag name on this XMLTag object.
184    @param inTagName the name of the requested subtags
185    @param inRecursion flag to indicate whether or not recursion should be used
186    @return the list of requested subtags
187    */
188   public <T extends XMLNode> List<T> getSubtagsByName(String inTagName, Recursion inRecursion);
189
190   //---------------------------------------------------------------------------
191   /**
192    Returns a List of all subtags with the specified tag name on this XMLTag object.
193    @param inTagName the name of the requested subtags
194    @param inRecursion flag to indicate whether or not recursion should be used
195    @return the list of requested subtags
196    */
197   public <T extends XMLNode> List<T> getSubtagsByName(XMLName inTagName, Recursion inRecursion);
198
199   //---------------------------------------------------------------------------
200   /**
201    Removes all subtags with the specified tag name from this XMLTag object.
202    @param inTagName the name of the subtags to remove
203    @return the list of removed subtags
204    */
205   public <T extends XMLNode> List<T> removeSubtagsByName(String inTagName);
206
207   //---------------------------------------------------------------------------
208   /**
209    Removes all subtags with the specified tag name from this XMLTag object.
210    @param inTagName the name of the subtags to remove
211    @return the list of removed subtags
212    */
213   public <T extends XMLNode> List<T> removeSubtagsByName(XMLName inTagName);
214
215   //---------------------------------------------------------------------------
216   /**
217    Returns a count of the total number of tags, including this root tag, its
218    subtags, the subtags' subtags, etc.
219    @return the total number of XML tags below and including this tag
220    */
221   public int getTotalTagCount();
222
223
224   //---------------------------------------------------------------------------
225   /**
226    Specifies the parent XMLContainer of this XMLContainer. Top level objects should
227    not have a parent.
228    @param inParent the XML node for which this tag should be a subnode
229    */
230   public void setParentNode(XMLContainer inParent);
231
232   //---------------------------------------------------------------------------
233   /**
234    Returns the parent XMLContainer of this XMLContainer. Top level objects should
235    return null.
236    @return the parent XML node of this node
237    */
238   public XMLContainer getParentNode();
239
240   //---------------------------------------------------------------------------
241   /**
242    Returns the previous sibling XMLContainer of this XMLContainer. Returns null if no sibling precedes this object.
243    @return the previous sibling XMLContainer of this XMLContainer. Returns null if no sibling follows this object.
244    */
245   public XMLContainer getPreviousSibling();
246
247   //---------------------------------------------------------------------------
248   /**
249    Returns the next sibling XMLContainer of this XMLContainer. Returns null if no sibling follows this object.
250    @return the next sibling XMLContainer of this XMLContainer. Returns null if no sibling follows this object.
251    */
252   public XMLContainer getNextSibling();
253
254}