001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/citations/tags/sakai_2-4-1/citations-api/api/src/java/org/sakaiproject/citation/api/CitationService.java $
003: * $Id: CitationService.java 29906 2007-05-03 13:22:13Z 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.util.List;
023: import java.util.Set;
024:
025: import org.osid.repository.Asset;
026: import org.sakaiproject.entity.api.Entity;
027: import org.sakaiproject.entity.api.EntityProducer;
028: import org.sakaiproject.exception.IdUnusedException;
029:
030: import org.sakaiproject.citation.api.Citation;
031: import org.sakaiproject.citation.api.CitationCollection;
032: import org.sakaiproject.citation.api.Schema;
033:
034: public interface CitationService extends EntityProducer {
035: /** This string can be used to find the service in the service manager. */
036: public static final String SERVICE_NAME = CitationService.class
037: .getName();
038:
039: /** The type string for this application: should not change over time as it may be stored in various parts of persistent entities. */
040: public static final String APPLICATION_ID = "sakai:citation";
041:
042: /** This string starts the references to entities in this service. */
043: public static final String REFERENCE_ROOT = Entity.SEPARATOR
044: + "citation";
045:
046: public static final String REF_TYPE_EXPORT_RIS_SEL = "export_ris_sel";
047: public static final String REF_TYPE_EXPORT_RIS_ALL = "export_ris_all";
048:
049: public static final String RIS_FORMAT = "RIS";
050:
051: public static final String UNKNOWN_TYPE = "unknown";
052:
053: public static final String REF_TYPE_VIEW_LIST = "list";
054:
055: public static final int DEFAULT_PAGE_SIZE = 10;
056:
057: /** Property name on a Citation that will cause getUrl() and getRefernce() to return an alternal root reference. */
058: public static final String PROP_ALTERNATE_REFERENCE = "sakai:reference-root";
059:
060: public static final String CITATION_LIST_ID = "org.sakaiproject.citation.impl.CitationList";
061: public static final String HELPER_ID = "sakai.citation.tool";
062:
063: public static final String PROP_TEMPORARY_CITATION_LIST = "citations.temporary_citation_list";
064:
065: /**
066: * Checks permissions to add a CitationList. Returns true if the user
067: * has permission to add a resource in the collection identified by the
068: * parameter.
069: * @param contentCollectionId
070: * @return
071: */
072: public boolean allowAddCitationList(String contentCollectionId);
073:
074: /**
075: * Checks permission to revise a CitationList, including permissions
076: * to add, remove or revise citations within the CitationList. Returns
077: * true if the user has permission to revise the resource identified by
078: * the parameter. Also returns true if all of these conditions are met:
079: * (1) the user is the creator of the specified resource, (2) the specified
080: * resource is a temporary CitationList (as identified by the value of
081: * the PROP_TEMPORARY_CITATION_LIST property), and (3) the user has
082: * permission to add resources in the collection containing the
083: * resource.
084: * @param contentResourceId
085: * @return
086: */
087: public boolean allowReviseCitationList(String contentResourceId);
088:
089: /**
090: *
091: * @return
092: */
093: public boolean allowRemoveCitationList(String contentResourceId);
094:
095: /**
096: *
097: * @param listId
098: * @return
099: */
100: public Citation addCitation(String mediatype);
101:
102: /**
103: * @return
104: */
105: public CitationCollection addCollection();
106:
107: /**
108: * @return
109: */
110: public CitationCollection getCollection(String collectionId)
111: throws IdUnusedException;
112:
113: /**
114: * @param collectionId
115: * @return
116: */
117: public CitationCollection copyAll(String collectionId);
118:
119: /**
120: * Access the default schema
121: * @return The default schema, or null if no schema has been set as the default.
122: */
123: public Schema getDefaultSchema();
124:
125: /**
126: * Access a schema by its name
127: * @param name The name of the schema
128: * @return The schema, or null if no schema has been defined with that name.
129: */
130: public Schema getSchema(String name);
131:
132: /**
133: * Access a list of all schemas that have been defined
134: * @return A list of Schema objects representing the schemas that have been defined.
135: */
136: public List getSchemas();
137:
138: /**
139: * Create a temporary citation that has not been saved in storage. Saving it or saving a collection
140: * it's a member of will convert it to a permanent citation and save it in storage.
141: * @return
142: */
143: public Citation getTemporaryCitation();
144:
145: /**
146: * Create a temporary citation to represent an asset. The new citation will not have been saved in
147: * storage yet. Saving it or saving a collection it's a member of will convert it to a permanent
148: * citation and save it in storage.
149: * @param asset
150: * @return
151: */
152: public Citation getTemporaryCitation(Asset asset);
153:
154: /**
155: * @return
156: */
157: public CitationCollection getTemporaryCollection();
158:
159: /**
160: * @return
161: */
162: public Set getValidPropertyNames();
163:
164: /**
165: * @param schemaId
166: * @param fieldId
167: * @return
168: */
169: public boolean isMultivalued(String schemaId, String fieldId);
170:
171: /**
172: * Access a list of identifiers for all schemas that have been defined
173: * @return A list of Strings representing the names of schemas that have been defined.
174: */
175: public List listSchemas();
176:
177: /**
178: * This method permanently removes a CitationCollection and all Citations it contains.
179: * @param edit The CitationCollection to remove.
180: */
181: public void removeCollection(CitationCollection edit);
182:
183: /**
184: *
185: * @param citation
186: */
187: public void save(Citation citation);
188:
189: /**
190: *
191: * @param collection
192: */
193: public void save(CitationCollection collection);
194:
195: } // interface CitationService
|