001: /**********************************************************************************
002: * $URL: $
003: * $Id: $
004: ***********************************************************************************
005: *
006: * Copyright (c) 2006, 2007 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.content.api;
021:
022: import java.io.InputStream;
023: import java.util.List;
024: import java.util.Map;
025:
026: /**
027: * ResourceToolActionPipe provides a conduit through which ResourcesAction and an
028: * unknown helper may communicate about the execution of ResourceToolActions in which
029: * the registered action specifies that some part of the action is handled by a helper.
030: *
031: * ResourceToolActionPipe has a set of methods through which ResourcesAction can pass
032: * information to a helper about the current state of the entity (or entities?) involved
033: * in an action ("setContent", "getContent", "setMimeType", "getMimeType", etc). It has
034: * another set of methods through which the helper passes back values that may or may
035: * not have been updated as a result of the action ("setRevisedContent", "getRevisedContent",
036: * "setRevisedMimeType", "getRevisedMimeType", etc). If a value is not changed by the action,
037: * the helper should use an appropriate setter to indicate the revised value is the same
038: * as the original value. For example:
039: *
040: * pipe.setRevisedMimeType( pipe.getMimeType() );
041: *
042: * Otherwise, the getter for the revised value will return null, and ResourcesAction will
043: * set unset the property. ResourceToolActionPipe also has a few methods through which the
044: * helper can report whether the action was canceled or an error was encountered.
045: *
046: * @see org.sakaiproject.content.api.ResourceTypeRegistry
047: * @see org.sakaiproject.content.api.ResourceToolAction
048: * @see org.sakaiproject.content.api.InteractionAction
049: */
050: public interface ResourceToolActionPipe {
051: /**
052: * @return
053: */
054: public ResourceToolAction getAction();
055:
056: /**
057: * Used by helper to access current value of resource's "content". Return will be
058: * empty array to indicate no content is defined for resource or null to indicate
059: * that content should be accessed as an OutputStream because of size or type of content.
060: * @return
061: */
062: public byte[] getContent();
063:
064: /**
065: * Used by helper to access current value of resource's "content" as a UTF-8 string. Return will be
066: * empty string to indicate no content is defined for resource or null to indicate
067: * that content should be accessed as an OutputStream because of size or type of content.
068: * @return
069: */
070: public String getContentstring();
071:
072: /**
073: * Used by helper to access an existing ContentEntity involved in this action. If the action
074: * is "create", the entity is a collection within which a new resource is being created.
075: * Otherwise the entity is a resource of the type involved in this action.
076: * @return
077: */
078: public ContentEntity getContentEntity();
079:
080: /**
081: * Used by helper to access current value of resource's "content" in cases where size
082: * or type of content requires stream access. Return may be null to indicate
083: * that content should be accessed as a byte array.
084: * @return
085: */
086: public InputStream getContentStream();
087:
088: /**
089: * Used only for actions of type ResourceToolAction.ActionType.NEW_UPLOAD.
090: * Retains the name of a file that has been uploaded recently as a reminder
091: * in the user interface.
092: * @return
093: */
094: public String getFileName();
095:
096: /**
097: * Used only for actions of type ResourceToolAction.ActionType.NEW_UPLOAD.
098: * @return
099: */
100: public int getFileUploadSize();
101:
102: /**
103: * Used by helper to access current mimetype of resource. Null value or empy string
104: * indicates that mimetype is irrelevant or unavailable.
105: * @return
106: */
107: public String getMimeType();
108:
109: /**
110: * Used by the Resources tool to retrieve error message that will be shown to user in
111: * its list view after completion of helper activity in which "error encountered" is set
112: * to true and an error is reported.
113: * @return
114: */
115: public String getErrorMessage();
116:
117: /**
118: * @return
119: */
120: public String getHelperId();
121:
122: /**
123: * Used by helper to access the initialization-id for this action, if an initialization-id
124: * was returned when ResourcesAction invoked the InteractionAction.initializeAction() method.
125: * The return value of this method will be null if an initialization-id was not supplied by
126: * that method.
127: * @return
128: */
129: public String getInitializationId();
130:
131: /**
132: * Used by helper to access current value of any resource property that has been specified
133: * by registrant in InteractionAction. Returns null if property value is not defined. Otherwise
134: * returns a String or a List of Strings
135: * @return
136: */
137: public Object getPropertyValue(String name);
138:
139: /**
140: * Used by ResourceAction to access helper's revised value of resource's "content". An empty
141: * array indicates that the resource has no content. A null value indicates that the content
142: * should be accessed as a stream.
143: * @return
144: */
145: public byte[] getRevisedContent();
146:
147: /**
148: * Used by ResourceAction to access helper's revised value of resource's "content". If both
149: * the byte-array and the stream are null, or if the byte-array is null and the stream does
150: * not contain any data, the resource is assumed to have no content.
151: * @return
152: */
153: public InputStream getRevisedContentStream();
154:
155: /**
156: * Used by ResourceAction to access helper's revised value for mimetype of resource.
157: * @return
158: */
159: public String getRevisedMimeType();
160:
161: /**
162: * Used by ResourceAction to access helper's revisions to values of resource properties.
163: * @return
164: */
165: public Map getRevisedResourceProperties();
166:
167: /**
168: * May be accessed by ResourcesAction after completion of helper activity to determine
169: * whether action was canceled. If the action was not canceled and no error was encountered,
170: * ResourcesAction will assume that the action completed successfully.
171: * @return
172: */
173: public boolean isActionCanceled();
174:
175: /**
176: * @return
177: */
178: public boolean isActionCompleted();
179:
180: /**
181: * May be accessed by ResourcesAction after completion of helper activity to determine
182: * whether an error was encountered. If the action was not canceled and no error was
183: * encountered, ResourcesAction will assume that the action completed successfully.
184: * @return
185: */
186: public boolean isErrorEncountered();
187:
188: /**
189: * Used by helper to indicate that User canceled the action and the action was not completed.
190: * @param actionCanceled
191: */
192: public void setActionCanceled(boolean actionCanceled);
193:
194: /**
195: * @param actionCompleted
196: */
197: public void setActionCompleted(boolean actionCompleted);
198:
199: /**
200: * Used by ResourcesAction to provide helper with current value of resource's "content".
201: * @return
202: */
203: public void setContent(byte[] content);
204:
205: /**
206: * Used by ResourcesAction to provide an existing ContentEntity involved in this action.
207: * If the action is "create", the entity is a collection within which a new resource is
208: * being created. Otherwise the entity is a resource of the type involved in this action.
209: * @param entity
210: */
211: public void setContentEntity(ContentEntity entity);
212:
213: /**
214: * Used by ResourcesAction to provide helper with alternative access to current value of resource's "content".
215: * @param content
216: */
217: public void setContentStream(InputStream ostream);
218:
219: /**
220: * Used by ResourcesAction to provide helper with mimetype of resource.
221: * @param ostream
222: */
223: public void setMimeType(String type);
224:
225: /**
226: * Used by helper to indicate that an error was encountered which prevented completion
227: * of the action.
228: * @param actionCanceled
229: */
230: public void setErrorEncountered(boolean errorEncountered);
231:
232: /**
233: * Used by helper to report error to user after completion of helper's portion of wizard.
234: * Most errors in the helper should be dealt with in the helper. This is for unusual errors
235: * that can not be dealt with in the helper and are tossed back to the Resources tool.
236: * If a message is reported and "error encountered" is set to true, the Resources tool
237: * will display the message in its list view. The message should be localized (i.e. read
238: * from a resource bundle).
239: * @param msg
240: */
241: public void setErrorMessage(String msg);
242:
243: /**
244: * Used by ResourcesAction to provide a value for the initialization-id. Should be initialized
245: * to the value returned by the InteractionAction.initializeAction() method (possibly null or
246: * an empty string is this information is not needed by the helper).
247: * @param
248: */
249: public void setInitializationId(String id);
250:
251: /**
252: * Used by ResourcesAction to provide helper with current value of a requested resource property
253: * whose value is a List of Strings.
254: * @param key
255: * @param list
256: */
257: public void setResourceProperty(String key, List list);
258:
259: /**
260: * Used by ResourcesAction to provide helper with current value of a requested resource property
261: * whose value is a single String.
262: * @param name
263: * @param value
264: */
265: public void setResourceProperty(String name, String value);
266:
267: /**
268: * Used by helper to provide ResourcesAction with revised value of resource's "content".
269: * @param content
270: */
271: public void setRevisedContent(byte[] content);
272:
273: /**
274: * Used by helper to provide ResourcesAction with revised value of resource's "content".
275: * @param stream
276: */
277: public void setRevisedContentStream(InputStream stream);
278:
279: /**
280: * Used by helper to provide ResourcesAction with revised mimetype of resource.
281: * Mimetype will not be referenced if param is null.
282: * @param type
283: */
284: public void setRevisedMimeType(String type);
285:
286: /**
287: * Used by helper to provide ResourcesAction with revised value for a resource property
288: * whose value is a List of Strings. Any property other than "live" properties can be set
289: * with this method. If action definition names the property and it is not set by this method,
290: * current value(s) will be removed.
291: * @param name
292: * @param list
293: */
294: public void setRevisedResourceProperty(String name, List list);
295:
296: /**
297: * Used by helper to provide ResourcesAction with revised value for a resource property.
298: * Any property other than "live" properties can be set with this method.
299: * If action definition names the property and it is not set by this method,
300: * current value will be removed.
301: * @param name
302: * @param value
303: */
304: public void setRevisedResourceProperty(String name, String value);
305:
306: /**
307: * @param helperId
308: */
309: public void setHelperId(String helperId);
310:
311: /**
312: * Used only for actions of type ResourceToolAction.ActionType.NEW_UPLOAD.
313: * Retains the name of a file that has been uploaded recently as a reminder
314: * in the user interface.
315: * @param fileName
316: */
317: public void setFileName(String fileName);
318:
319: /**
320: * Used only for individual pipes contained within a MultiFileUploadPipe, to
321: * return values of properties set in the helper. The parameter must be an instance
322: * of org.sakaiproject.content.tool.ListItem. The Resources tool will ignore
323: * the item unless it is an instance of org.sakaiproject.content.tool.ListItem.
324: * @param item
325: */
326: public void setRevisedListItem(Object item);
327:
328: /**
329: * Used by the Resources tool to retrieve aListItem from an individual pipe
330: * contained within a MultiFileUploadPipe. The Resources tool assumes the
331: * values of properties set by the helper are to be used in creating a new
332: * entity. The Resources tool will ignore the item unless it is an instance of
333: * org.sakaiproject.content.tool.ListItem.
334: * @return
335: */
336: public Object getRevisedListItem();
337: }
|