001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/citations/tags/sakai_2-4-1/citations-api/api/src/java/org/sakaiproject/citation/api/CitationCollection.java $
003: * $Id: CitationCollection.java 29627 2007-04-26 14:37:26Z ajpoland@iupui.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2006 The Sakai Foundation.
007: *
008: * Licensed under the Educational Community License, Version 1.0 (the "License");
009: * you may not use this file except in compliance with the License.
010: * You may obtain a copy of the License at
011: *
012: * http://www.opensource.org/licenses/ecl1.php
013: *
014: * Unless required by applicable law or agreed to in writing, software
015: * distributed under the License is distributed on an "AS IS" BASIS,
016: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
017: * See the License for the specific language governing permissions and
018: * limitations under the License.
019: *
020: **********************************************************************************/package org.sakaiproject.citation.api;
021:
022: import java.io.IOException;
023: import java.io.OutputStream;
024: import java.util.Comparator;
025: import java.util.List;
026:
027: import org.sakaiproject.citation.util.api.SearchException;
028: import org.sakaiproject.entity.api.Entity;
029: import org.sakaiproject.exception.IdUnusedException;
030:
031: /**
032: *
033: *
034: */
035: public interface CitationCollection extends Entity {
036: public final static String SORT_BY_AUTHOR = "author";
037: public final static String SORT_BY_TITLE = "title";
038: public final static String SORT_BY_UUID = "uuid";
039: public final static String SORT_BY_DEFAULT_ORDER = "default";
040:
041: public String getSaveUrl();
042:
043: /**
044: * Appends the specified Citation at the end of this list.
045: * @param element
046: * @return true if the list changed as a result of this operation.
047: */
048: public void add(Citation element);
049:
050: /**
051: * Appends all of the Citations in the specified CitationCollection to the end of this CitationCollection, in the order that they are
052: * returned by the specified CitationCollection's iterator. This operation fails if this list and the other list are the same
053: * Object.
054: * @param other The list containing the Citations to be appended to this list.
055: * @return true if the list changed as a result of this operation.
056: */
057: public void addAll(CitationCollection other);
058:
059: /**
060: * Access a sorted list of all Citations belonging to the CitationCollection, where the sort order is
061: * determined by the Comparator (@see http://java.sun.com/j2se/1.4.2/docs/api/java/util/Comparator.html).
062: * @param c The comparator that determines the relative ordering of any two Citations.
063: * @return The sorted list of Citations. May be empty but will not be null.
064: */
065: // public CitationCollection getCitations(Comparator c);
066: /**
067: * Access an ordered list of a subset of the Citations belonging to the CitationCollection, where membership in the subset is
068: * determined by the filter (@see Filter).
069: * @param f The filter that determines membership in the subset.
070: * @return The filtered list of Citations. May be empty but will not be null.
071: */
072: // public CitationCollection getCitations(Filter f);
073: /**
074: * Access a sorted list of a subset of the Citations belonging to the CitationCollection, where the sort order is
075: * determined by the Comparator (@see http://java.sun.com/j2se/1.4.2/docs/api/java/util/Comparator.html) and
076: * membership in the subset is determined by the filter (@see Filter).
077: * @param c The comparator that determines the relative ordering of any two Citations.
078: * @param f The filter that determines membership in the subset.
079: * @return The sorted, filtered list of Citations. May be empty but will not be null.
080: */
081: // public CitationCollection getCitations(Comparator c, Filter f);
082: /**
083: * Access all Citations in the list with name-value pairs in their properties matching the name-value pairs in
084: * the properties parameter. Returns a list of Citations satisfying the criteria, which may be empty if no Citations
085: * in the list satisfy the criteria.
086: * @param properties A mapping of name-value pairs indicating names of properties as Strings and values of properties as Strings.
087: * @return the list of elements that match, which may be empty but not null.
088: */
089: // public CitationCollection getCitations(Map properties);
090: /**
091: *
092: */
093: public void clear();
094:
095: /**
096: * Access a particular Citation from the list.
097: * @param index The index the the Citation in the unsorted, unfiltered list.
098: * @return The Citation.
099: */
100: // public Citation getCitation(int index);
101: /**
102: * Access the first occurrence in this list of a Citation with name-value pairs in its properties matching the name-value pairs in
103: * the properties parameter. Returns the element, or null if no element in the list matched the properties.
104: * @param properties A mapping of name-value pairs indicating names of properties as Strings and values of properties as Strings.
105: * @return the first element that matches, or null if no element in the list matches the properties.
106: */
107: // public Citation getCitation(Map properties);
108: /**
109: * @param item
110: * @return
111: */
112: public boolean contains(Citation item);
113:
114: /**
115: * Returns an iterator over the Citation objects in this CitationCollection.
116: * @return an Iterator over the Citation objects in this CitationCollection
117: */
118: // public Iterator iterator();
119: /**
120: * Access a particular Citation from the list.
121: * @param id
122: * @return The Citation.
123: */
124: public Citation getCitation(String id) throws IdUnusedException;
125:
126: /**
127: * Access an ordered list of all Citations belonging to the CitationCollection.
128: * @return The ordered list of Citation objects. May be empty but will not be null.
129: */
130: public List getCitations();
131:
132: // public boolean containsAll(CitationCollection list);
133:
134: /**
135: * Returns the index in this list of the first occurrence of the specified Citation, or -1 if this list does not contain this Citation.
136: * @param item The element to search for.
137: * @return the index in this list of the first occurrence of the specified Citation, or -1 if this list does not contain this Citation.
138: */
139: // public int indexOf(Citation item);
140: /**
141: * Returns the index in this list of the last occurrence of the specified Citation, or -1 if this list does not contain this Citation.
142: * @param item The element to search for.
143: * @return the index in this list of the last occurrence of the specified Citation, or -1 if this list does not contain this Citation.
144: */
145: // public int lastIndexOf(Citation item);
146: /**
147: * @param c
148: */
149: // public void sort(Comparator c);
150: /**
151: * Move an item from one place in the list to another.
152: * @param from The index of the element to be moved.
153: * @param to The index the element should have after the move.
154: * @return true if the move succeeded.
155: */
156: // public boolean move(int from, int to);
157: /**
158: * Move an item from a specified index in the list to the beginning of the list (index of 0).
159: * @param index
160: * @return true if the move succeeded.
161: */
162: // public boolean moveToFront(int index);
163: /**
164: * Move an item from a specified index in the list to the end of the list (index of list.size() - 1).
165: * @param index
166: * @return true if the move succeeded.
167: */
168: // public boolean moveToBack(int index);
169: /**
170: * Inserts the specified Citation at the specified position in this list.
171: * @param index
172: * @param element
173: * @return true if the list changed as a result of this operation.
174: */
175: // public boolean add(int index, Citation element);
176: /**
177: * @return
178: */
179: public String getDescription();
180:
181: /**
182: * Access the unique identifier for this CitationCollection.
183: */
184: public String getId();
185:
186: /**
187: * Inserts all of the Citations in the specified CitationCollection into this CitationCollection, in the order that they are returned by
188: * the specified CitationCollection's iterator, beginning at the location indicated by the index parameter. Shifts any subsequent
189: * elements to the right (increases their indices by the number indicating the size of the other list). This operation fails
190: * if this list and the other list are the same Object.
191: * @param index The offset from the beginning of this list at which the first Citation from the other list should be inserted.
192: * @param other The list containing the Citations to be inserted into this list.
193: * @return true if the list changed as a result of this operation.
194: */
195: // public boolean addAll(int index, CitationCollection other);
196: /**
197: * Removes all of the elements from this list.
198: */
199: // public void clear();
200: /**
201: * Removes the element at the specified position in this list. Shifts any subsequent elements to the left (subtracts one from their
202: * indices). Returns the element that was removed from the list (null if index out of bounds).
203: * @param index
204: * @return the element that was removed from the list (null if index out of bounds)
205: */
206: // public Citation remove(int index);
207: /**
208: * Removes the first occurrence in this list of a Citation with name-value pairs in its properties matching the name-value pairs in
209: * the properties parameter. Shifts any subsequent elements to the left (subtracts one from their indices). Returns the element that
210: * was removed from the list (null if no element in the list matched the properties).
211: * @param item The element to be removed from the list, if present.
212: * @return the element that was removed from the list (null if no element in the list matched the properties).
213: */
214: // public Citation remove(Map properties);
215: /**
216: * @return
217: */
218: public String getTitle();
219:
220: /**
221: * Returns true if this collection contains no elements.
222: * @return true if this collection contains no elements.
223: */
224: public boolean isEmpty();
225:
226: /**
227: * @return
228: */
229: public CitationIterator iterator();
230:
231: /**
232: * Removes the first occurrence in this list of the specified Citation. Shifts any subsequent elements to the left (subtracts one from
233: * their indices). Returns true if the list contained the specified citation.
234: * @param item The element to be removed from the list, if present.
235: * @return true if the list changed as a result of this call.
236: */
237: public boolean remove(Citation item);
238:
239: /**
240: * @param citation
241: */
242: public void saveCitation(Citation citation);
243:
244: /**
245: *
246: * @param comparator
247: */
248: public void setSort(Comparator comparator);
249:
250: /**
251: *
252: * @param sortBy
253: * @param ascending
254: */
255: public void setSort(String sortBy, boolean ascending);
256:
257: /**
258: * Access the number of citations in this collection.
259: * @return
260: */
261: public int size();
262:
263: /**
264: *
265: * @param buffer
266: * @param citationIds
267: * @throws IOException
268: */
269: public void exportRis(StringBuffer buffer, List<String> citationIds)
270: throws IOException;
271:
272: } // interface Citation
|