001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/citations/tags/sakai_2-4-1/citations-api/api/src/java/org/sakaiproject/citation/api/Citation.java $
003: * $Id: Citation.java 22437 2007-03-12 18:13:35Z jimeng@umich.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.InputStream;
024: import java.io.OutputStream;
025: import java.net.URL;
026: import java.util.List;
027: import java.util.Map;
028:
029: import org.sakaiproject.entity.api.Entity;
030: import org.sakaiproject.exception.IdUnusedException;
031:
032: /**
033: *
034: *
035: */
036: public interface Citation // extends Entity
037: {
038: /**
039: * @param label
040: * @param url
041: * @return A unique identifier for the URL and its label.
042: */
043: public void addCustomUrl(String label, String url);
044:
045: /**
046: * @param name
047: * @param value
048: */
049: public void addPropertyValue(String name, Object value);
050:
051: /**
052: * Write this citation in RIS format to an output stream
053: * @param buffer
054: * @throws IOException
055: */
056: public void exportRis(StringBuffer buffer) throws IOException;
057:
058: /**
059: * Access a mapping of name-value pairs for various bibliographic information about the resource.
060: * Ideally, the names will be expressed as URIs for standard tags representing nuggets of bibliographic metadata.
061: * Values will be strings in formats specified by the standards defining the property names. For example if the
062: * name is a URI referencing a standard format for a "publication_date" and the standard indicates that the value
063: * should be expressed as in xs:date format, the value should be expressed as a string representation of xs:date.
064: * @return The mapping of name-value pairs. The mapping may be empty, but it should never be null.
065: */
066: public Map getCitationProperties();
067:
068: /**
069: * Access a representation of the value(s) of a named property. If the property is multivalued,
070: * the object returned will be a (possibly empty) java.util.List. Otherwise it will be an Object
071: * of a type appropriate for the named property (usually a String or a Date). The value(s)
072: * must be of a type for which toString() is defined and returns a reasonable representation
073: * for use in a textual display of the citation.
074: * @param name The name of the property for which a value is to be returned.
075: * @return A representation of the value(s) of the named property. May be an empty String ("")
076: * if the property is not defined.
077: */
078: public Object getCitationProperty(String name);
079:
080: /**
081: * @return
082: */
083: public String getCreator();
084:
085: /**
086: * @param id
087: * @return
088: */
089: public String getCustomUrl(String id) throws IdUnusedException;
090:
091: /**
092: * @return
093: */
094: public List getCustomUrlIds();
095:
096: /**
097: * @param id
098: * @return
099: * @throws IdUnusedException
100: */
101: public String getCustomUrlLabel(String id) throws IdUnusedException;
102:
103: /**
104: * Access the brief "title" of the resource, which can be used to display the item in a list of items.
105: * @return The display name.
106: */
107: public String getDisplayName();
108:
109: /**
110: * @return
111: */
112: public String getFirstAuthor();
113:
114: /**
115: * @return
116: */
117: public String getId();
118:
119: /**
120: * @return
121: */
122: public String getOpenurl();
123:
124: /**
125: * @return
126: */
127: public String getOpenurlParameters();
128:
129: public String getSaveUrl(String collectionId);
130:
131: /**
132: * Access the schema for the Citation
133: * @return th
134: */
135: public Schema getSchema();
136:
137: /**
138: * @return
139: */
140: public String getSource();
141:
142: /**
143: * @return
144: */
145: public boolean hasCustomUrls();
146:
147: /**
148: * @return
149: */
150: public boolean hasPropertyValue(String fieldId);
151:
152: /**
153: * Read this citation from an input stream in RIS format
154: * @param istream
155: * @throws IOException
156: */
157: public void importFromRis(InputStream istream) throws IOException;
158:
159: /**
160: * @return
161: */
162: public boolean isAdded();
163:
164: /**
165: * @param fieldId
166: * @return
167: */
168: public boolean isMultivalued(String fieldId);
169:
170: /**
171: * Access a list of names of citation properties defined for this resource.
172: * @return The list of property names. The list may be empty, but it should never be null.
173: */
174: public List listCitationProperties();
175:
176: /**
177: * @param added
178: */
179: public void setAdded(boolean added);
180:
181: /**
182: * @param name
183: * @param value
184: */
185: public void setCitationProperty(String name, Object value);
186:
187: /**
188: * @param name
189: */
190: public void setDisplayName(String name);
191:
192: /**
193: * @param schema
194: */
195: public void setSchema(Schema schema);
196:
197: /**
198: * Replaces the current value(s) of a citation property. If the field identified by the parameter "name"
199: * is multivalued, the values in the list parameter "values" replace the current values. If the field is
200: * single valued, the first value in the list "values" replaces the current value. In either case, if the
201: * values parameter is null or empty, all current values are removed and no new values are added.
202: *
203: * @param name
204: * @param values
205: */
206: public void updateCitationProperty(String name, List values);
207:
208: /**
209: * @param urlid
210: * @param label
211: * @param url
212: */
213: public void updateCustomUrl(String urlid, String label, String url);
214:
215: } // interface Citation
|