001 /*
002 * Created by IntelliJ IDEA.
003 * User: d@hd.org
004 * Date: 18-May-02
005 * Time: 15:46:38
006
007 Copyright (c) 1996-2011, Damon Hart-Davis
008 All rights reserved.
009
010 Redistribution and use in source and binary forms, with or without
011 modification, are permitted provided that the following conditions are
012 met:
013
014 * Redistributions of source code must retain the above copyright
015 notice, this list of conditions and the following disclaimer.
016
017 * Redistributions in binary form must reproduce the above copyright
018 notice, this list of conditions and the following disclaimer in the
019 documentation and/or other materials provided with the
020 distribution.
021
022 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
023 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
024 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
025 PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
026 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
027 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
028 LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
029 DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
030 THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
031 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
032 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
033
034 */
035 package org.hd.d.pg2k.webSvr.util;
036
037 import java.io.Serializable;
038 import java.util.Collections;
039 import java.util.List;
040 import java.util.Vector;
041
042 /**Holds the data corresponding to a breadcrumbs navigation aid on a Web page.
043 * This consists of a list of text/hyperlink pairs,
044 * running from the largest/outermost part of the Website first,
045 * to the innermost part (corresponding to that nearest the current page) last.
046 * <p>
047 * It is possible to insert items at start or end,
048 * though most efficient to insert at the end.
049 * <p>
050 * It is possible to insert items with no link, but not with no text.
051 * <p>
052 * This can export a read-only view of its content as a List.
053 * <p>
054 * This is thread-safe and Serializable so as to be able to be stored in
055 * a servlet session; nothing especially long-lived or sensitive.
056 */
057 public final class Breadcrumbs implements java.io.Serializable
058 {
059 /**This is our list of breadcrumbs, in order.
060 * We use a Vector so as to be inherently thread-safe.
061 * <p>
062 * We expect that usually we will have no more than about
063 * four crumbs, and so default to that size.
064 */
065 private final List<Breadcrumb> crumbs = new Vector<Breadcrumb>(4);
066
067 /**Returns read-only view of the crumbs as a List.
068 */
069 public List<Breadcrumb> viewAsList() { return(Collections.unmodifiableList(crumbs)); }
070
071 /**Returns <tt>true</tt> if there are no breadcrumbs.
072 */
073 public boolean isEmpty() { return(crumbs.isEmpty()); }
074
075 /**Returns the number of crumbs.
076 */
077 public int size() { return(crumbs.size()); }
078
079 /**Removes all of the crumbs.
080 */
081 public void clear() { crumbs.clear(); }
082
083 /**Appends crumb (to end of list).
084 * Crumb must not be null.
085 */
086 public void append(final Breadcrumb crumbForEnd)
087 {
088 if(crumbForEnd == null) { throw new IllegalArgumentException(); }
089 crumbs.add(crumbForEnd);
090 }
091
092 /**Prepends crumb (to start of list).
093 * Crumb must not be null.
094 */
095 public void prepend(final Breadcrumb crumbForStart)
096 {
097 if(crumbForStart == null) { throw new IllegalArgumentException(); }
098 crumbs.add(0, crumbForStart);
099 }
100
101 /**Get specified crumb by its index.
102 * @throws IndexOutOfBoundsException if the index is invalid
103 */
104 public Breadcrumb getCrumb(final int index)
105 throws IndexOutOfBoundsException
106 { return(crumbs.get(index)); }
107
108 /**Unique Serialisation class ID generated by http://random.hd.org/. */
109 private static final long serialVersionUID = -7990918038988551161L;
110
111
112 /**One item in the breadcrumbs. */
113 public static final class Breadcrumb implements Serializable
114 {
115 /**The text of the link; never null nor zero-length. */
116 public final String linkText;
117 /**The URL (possibly relative); never zero-length but may be null. */
118 public final String link;
119
120 /**Make a breadcrumb.
121 *
122 * @param text the text for the breadcrumb link; must not be null nor
123 * zero-length
124 * @param url the absolute or relative URL; can be null if not needed
125 */
126 public Breadcrumb(final String text, final String url)
127 {
128 if((text == null) || (text.length() == 0))
129 { throw new IllegalArgumentException("link text cannot be empty"); }
130 if(url == null)
131 { throw new IllegalArgumentException("link cannot be zero-length"); }
132 linkText = text;
133 link = url;
134 }
135
136 /**Unique Serialisation class ID generated by http://random.hd.org/. */
137 private static final long serialVersionUID = 6755765230040158278L;
138 }
139 }