001: /**********************************************************************************
002: * $URL: https://source.sakaiproject.org/svn/entity/tags/sakai_2-4-1/entity-api/api/src/java/org/sakaiproject/entity/api/Reference.java $
003: * $Id: Reference.java 29631 2007-04-26 14:39:15Z ajpoland@iupui.edu $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2003, 2004, 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:
024: /**
025: * <p>
026: * Reference holds an immutable reference to a Sakai entity.
027: * </p>
028: */
029: public interface Reference {
030: /**
031: * Add the AuthzGroup(s) for context as a site.
032: *
033: * @param rv
034: * The list.
035: */
036: void addSiteContextAuthzGroup(Collection rv);
037:
038: /**
039: * Add the AuthzGroup for this user id, or for the user's type template, or for the general template.
040: *
041: * @param rv
042: * The list.
043: * @param id
044: * The user id.
045: */
046: void addUserAuthzGroup(Collection rv, String id);
047:
048: /**
049: * Add the AuthzGroup for this user id, or for the user's type template, or for the general template.
050: *
051: * @param rv
052: * The list.
053: * @param id
054: * The user id.
055: */
056: void addUserTemplateAuthzGroup(Collection rv, String id);
057:
058: /**
059: * Access a single container id, the from most general (or only)
060: *
061: * @return The single or most general container, if any.
062: */
063: String getContainer();
064:
065: /**
066: * Access the context id, if any.
067: *
068: * @return the context id, if any.
069: */
070: String getContext();
071:
072: /**
073: * @return a description of the resource referenced.
074: */
075: String getDescription();
076:
077: /**
078: * Find the Entity that is referenced.
079: *
080: * @return The Entity object that this references.
081: */
082: Entity getEntity();
083:
084: /**
085: * Access the primary id.
086: *
087: * @return The primary id.
088: */
089: String getId();
090:
091: /**
092: * Find the ResourceProperties object for this reference.
093: *
094: * @return A ResourcesProperties object found (or constructed) for this reference.
095: */
096: ResourceProperties getProperties();
097:
098: /**
099: * Compute the set of AuthzGroup ids associated with this referenced resource.
100: *
101: * @return List of AuthzGroup ids (String) associated with this referenced resource.
102: */
103: Collection getAuthzGroups();
104:
105: /**
106: * Compute the set of AuthzGroup ids associated with this referenced resource, perhaps customized for security about this end user.
107: *
108: * @param userId
109: * the end user ID, or null if we want the generic set.
110: * @return List of AuthzGroup ids (String) associated with this referenced resource.
111: */
112: Collection getAuthzGroups(String userId);
113:
114: /**
115: * Access the reference.
116: *
117: * @return The reference.
118: */
119: String getReference();
120:
121: /**
122: * Access the subType.
123: *
124: * @return The subType.
125: */
126: String getSubType();
127:
128: /**
129: * Access the type, an application id string. This value must uniquely identify the application responsible for the reference, and must be unchanging over time (it may end up stored in database values).
130: *
131: * @return The type, an application id string.
132: */
133: String getType();
134:
135: /**
136: * Access the URL which can be used to access the referenced resource.
137: *
138: * @return The URL which can be used to access the referenced resource.
139: */
140: String getUrl();
141:
142: /**
143: * Check if the reference's type is known
144: *
145: * @return true if known, false if not.
146: */
147: boolean isKnownType();
148:
149: /**
150: * Accept the settings for a reference - may be rejected if already set
151: *
152: * @param type
153: * @param subType
154: * @param id
155: * @param container
156: * @param container2
157: * @param context
158: * @return true if settings are accepted, false if not.
159: */
160: boolean set(String type, String subType, String id,
161: String container, String context);
162:
163: /**
164: * Update the reference string.
165: *
166: * @param ref The new reference string.
167: */
168: void updateReference(String ref);
169:
170: /**
171: * Access the entity producer responsible for the referenced entity.
172: *
173: * @return The EntityProducer responsible for the referenced entity, or null if there is none.
174: */
175: EntityProducer getEntityProducer();
176: }
|