001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/entity/tags/sakai_2-4-1/entity-api/api/src/java/org/sakaiproject/entity/api/EntityProducer.java $
003: * $Id: EntityProducer.java 10976 2006-06-21 18:48:20Z ggolden@umich.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2005, 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.entity.api;
021:
022: import java.util.Collection;
023: import java.util.List;
024: import java.util.Map;
025: import java.util.Set;
026: import java.util.Stack;
027:
028: import org.w3c.dom.Document;
029: import org.w3c.dom.Element;
030:
031: /**
032: * <p>
033: * Services which implement EntityProducer declare themselves as producers of Sakai entities.
034: * </p>
035: */
036: public interface EntityProducer {
037: /**
038: * @return a short string identifying the resources kept here, good for a file name or label.
039: */
040: String getLabel();
041:
042: /**
043: * @return true if the serice wants to be part of archive / merge, false if not.
044: */
045: boolean willArchiveMerge();
046:
047: /**
048: * Archive the resources for the given site.
049: *
050: * @param siteId
051: * the id of the site.
052: * @param doc
053: * The document to contain the xml.
054: * @param stack
055: * The stack of elements, the top of which will be the containing element of the "service.name" element.
056: * @param archivePath
057: * The path to the folder where we are writing auxilary files.
058: * @param attachments
059: * A list of attachments - add to this if any attachments need to be included in the archive.
060: * @return A log of status messages from the archive.
061: */
062: String archive(String siteId, Document doc, Stack stack,
063: String archivePath, List attachments);
064:
065: /**
066: * Merge the resources from the archive into the given site.
067: *
068: * @param siteId
069: * The id of the site getting imported into.
070: * @param root
071: * The XML DOM tree of content to merge.
072: * @param archviePath
073: * The path to the folder where we are reading auxilary files.
074: * @param fromSite
075: * The site id from which these items were archived.
076: * @param attachmentNames
077: * A map of old attachment name (as found in the DOM) to new attachment name.
078: * @return A log of status messages from the merge.
079: */
080: String merge(String siteId, Element root, String archivePath,
081: String fromSiteId, Map attachmentNames, Map userIdTrans,
082: Set userListAllowImport);
083:
084: /**
085: * If the service recognizes the reference as its own, parse it and fill in the Reference
086: *
087: * @param reference
088: * The reference string to examine.
089: * @param ref
090: * The Reference object to set with the results of the parse from a recognized reference.
091: * @return true if the reference belonged to the service, false if not.
092: */
093: boolean parseEntityReference(String reference, Reference ref);
094:
095: /**
096: * Create an entity description for the entity referenced - the entity will belong to the service.
097: *
098: * @param ref
099: * The entity reference.
100: * @return The entity description, or null if one cannot be made.
101: */
102: String getEntityDescription(Reference ref);
103:
104: /**
105: * Access the resource properties for the referenced entity - the entity will belong to the service.
106: *
107: * @param ref
108: * The entity reference.
109: * @return The ResourceProperties object for the entity, or null if it has none.
110: */
111: ResourceProperties getEntityResourceProperties(Reference ref);
112:
113: /**
114: * Access the referenced Entity - the entity will belong to the service.
115: *
116: * @param ref
117: * The entity reference.
118: * @return The Entity, or null if not found.
119: */
120: Entity getEntity(Reference ref);
121:
122: /**
123: * Access a URL for the referenced entity - the entity will belong to the service.
124: *
125: * @param ref
126: * The entity reference.
127: * @return The entity's URL, or null if it does not have one.
128: */
129: String getEntityUrl(Reference ref);
130:
131: /**
132: * Access a collection of authorization group ids for security on the for the referenced entity - the entity will belong to the service.
133: *
134: * @param ref
135: * The entity reference.
136: * @param userId
137: * The userId for a user-specific set of groups, or null for the generic set.
138: * @return The entity's collection of authorization group ids, or null if this cannot be done.
139: */
140: Collection getEntityAuthzGroups(Reference ref, String userId);
141:
142: /**
143: * Get the HttpAccess object that supports entity access via the access servlet for my entities.
144: *
145: * @return The HttpAccess object for my entities, or null if I do not support access.
146: */
147: HttpAccess getHttpAccess();
148: }
|