1 /** 2 * Copyright 2010 The Kuali Foundation Licensed under the 3 * Educational Community License, Version 2.0 (the "License"); you may 4 * not use this file except in compliance with the License. You may 5 * obtain a copy of the License at 6 * 7 * http://www.osedu.org/licenses/ECL-2.0 8 * 9 * Unless required by applicable law or agreed to in writing, 10 * software distributed under the License is distributed on an "AS IS" 11 * BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express 12 * or implied. See the License for the specific language governing 13 * permissions and limitations under the License. 14 */ 15 16 package org.kuali.student.core.comment.service; 17 18 import java.util.List; 19 20 import javax.jws.WebParam; 21 import javax.jws.WebService; 22 import javax.jws.soap.SOAPBinding; 23 24 import org.kuali.student.common.dictionary.service.DictionaryService; 25 import org.kuali.student.common.dto.ReferenceTypeInfo; 26 import org.kuali.student.common.dto.StatusInfo; 27 import org.kuali.student.common.exceptions.AlreadyExistsException; 28 import org.kuali.student.common.exceptions.DataValidationErrorException; 29 import org.kuali.student.common.exceptions.DoesNotExistException; 30 import org.kuali.student.common.exceptions.InvalidParameterException; 31 import org.kuali.student.common.exceptions.MissingParameterException; 32 import org.kuali.student.common.exceptions.OperationFailedException; 33 import org.kuali.student.common.exceptions.PermissionDeniedException; 34 import org.kuali.student.common.exceptions.VersionMismatchException; 35 import org.kuali.student.common.validation.dto.ValidationResultInfo; 36 import org.kuali.student.core.comment.dto.CommentInfo; 37 import org.kuali.student.core.comment.dto.CommentTypeInfo; 38 import org.kuali.student.core.comment.dto.TagInfo; 39 import org.kuali.student.core.comment.dto.TagTypeInfo; 40 41 /** 42 * 43 * @Author KSContractMojo 44 * @Author Neerav Agrawal 45 * @Since Fri Jun 05 14:27:10 EDT 2009 46 * @See <a href="https://test.kuali.org/confluence/display/KULSTR/Comment+Service+v1.0-rc1">CommentService</> 47 * 48 */ 49 @WebService(name = "CommentService", targetNamespace = "http://student.kuali.org/wsdl/comment") 50 @SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.WRAPPED) 51 //@XmlSeeAlso({org.kuali.student.core.dto.ReferenceTypeInfo.class}) 52 public interface CommentService extends DictionaryService { 53 /** 54 * Retrieves the list of types which can be tagged or commented. 55 * @return the list of types which can be tagged or commented 56 * @throws OperationFailedException unable to complete request 57 */ 58 public List<ReferenceTypeInfo> getReferenceTypes() throws OperationFailedException; 59 60 /** 61 * Retrieves the list of comment types which can be linked to a referenced object. 62 * @return the list of comment types which can be linked to a referenced object 63 * @throws OperationFailedException unable to complete request 64 */ 65 public List<CommentTypeInfo> getCommentTypes() throws OperationFailedException; 66 67 /** 68 * Retrieves the list of tag types which can be linked to a referenced object. 69 * @return the list of tag types which can be linked to a referenced object 70 * @throws OperationFailedException unable to complete request 71 */ 72 public List<TagTypeInfo> getTagTypes() throws OperationFailedException; 73 74 /** 75 * Retrieves the list of comment types which can be linked to a particular type of referenced object. 76 * @param referenceTypeKey reference type 77 * @return the list of comment types which can be linked to a referenced object type 78 * @throws DoesNotExistException specified referenceTypeKey not found 79 * @throws InvalidParameterException invalid referenceTypeKey 80 * @throws MissingParameterException referenceTypeKey not specified 81 * @throws OperationFailedException unable to complete request 82 */ 83 public List<CommentTypeInfo> getCommentTypesForReferenceType(@WebParam(name="referenceTypeKey")String referenceTypeKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException; 84 85 /** 86 * Validates a comment. Depending on the value of validationType, this validation could be limited to tests on just the current object and its directly contained sub-objects or expanded to perform all tests related to this object. If an identifier is present for the comment (and/or one of its contained sub-objects) and a record is found for that identifier, the validation checks if the comment can be shifted to the new values. If an identifier is not present or a record cannot be found for the identifier, it is assumed that the record does not exist and as such, the checks performed will be much shallower, typically mimicking those performed by setting the validationType to the current object. 87 * @param validationType identifier of the extent of validation 88 * @param commentInfo comment information to be tested. 89 * @return results from performing the validation 90 * @throws DoesNotExistException validationTypeKey not found 91 * @throws InvalidParameterException invalid validationTypeKey, commentInfo 92 * @throws MissingParameterException missing validationTypeKey, commentInfo 93 * @throws OperationFailedException unable to complete request 94 */ 95 public List<ValidationResultInfo> validateComment(@WebParam(name="validationType")String validationType, @WebParam(name="commentInfo")CommentInfo commentInfo) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException; 96 97 /** 98 * Retrieves comment information for a reference. The expected behavior is that if the caller is not authorized to invoke the getComments operation, a PERMISSION_DENIED error is returned. Assuming that the caller is authorized to invoke getComments, only comments that the caller is authorized to view are included in the returned commentInfoList; comments that the caller is unauthorized to view are filtered out of the return parameter. 99 * @param referenceId reference identifier 100 * @param referenceTypeKey reference type 101 * @return list of comment information 102 * @throws DoesNotExistException specified referenceId, referenceTypeKey not found 103 * @throws InvalidParameterException invalid referenceId, referenceTypeKey 104 * @throws MissingParameterException referenceId, referenceTypeKey not specified 105 * @throws OperationFailedException unable to complete request 106 * @throws PermissionDeniedException authorization failure 107 */ 108 public List<CommentInfo> getComments(@WebParam(name="referenceId")String referenceId, @WebParam(name="referenceTypeKey")String referenceTypeKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 109 110 /** 111 * Retrieves tag information for a reference. The expected behavior is that if the caller is not authorized to invoke the getTags operation, a PERMISSION_DENIED error is returned. Assuming that the caller is authorized to invoke getTags, only tags that the caller is authorized to view are included in the returned tagInfoList; tags that the caller is unauthorized to view are filtered out of the return parameter. 112 * @param referenceId reference identifier 113 * @param referenceTypeKey reference type 114 * @return list of tag information 115 * @throws DoesNotExistException specified referenceId, referenceTypeKey not found 116 * @throws InvalidParameterException invalid referenceId, referenceTypeKey 117 * @throws MissingParameterException referenceId, referenceTypeKey not specified 118 * @throws OperationFailedException unable to complete request 119 * @throws PermissionDeniedException authorization failure 120 */ 121 public List<TagInfo> getTags(@WebParam(name="referenceId")String referenceId, @WebParam(name="referenceTypeKey")String referenceTypeKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 122 123 /** 124 * Retrieves comment information for a reference of a particular type. The expected behavior is that if the caller is not authorized to invoke the getCommentsByType operation, a PERMISSION_DENIED error is returned. Assuming that the caller is authorized to invoke getCommentsByType, only comments that the caller is authorized to view are included in the returned commentInfoList; comments that the caller is unauthorized to view are filtered out of the return parameter. 125 * @param referenceId reference identifier 126 * @param referenceTypeKey reference type 127 * @param commentTypeKey comment type 128 * @return list of comment information 129 * @throws DoesNotExistException specified referenceId, referenceTypeKey, commentTypeKey not found 130 * @throws InvalidParameterException invalid referenceId, referenceTypeKey,commentTypeKey 131 * @throws MissingParameterException referenceId, referenceTypeKey, commentTypeKey not specified 132 * @throws OperationFailedException unable to complete request 133 * @throws PermissionDeniedException authorization failure 134 */ 135 public List<CommentInfo> getCommentsByType(@WebParam(name="referenceId")String referenceId, @WebParam(name="referenceTypeKey")String referenceTypeKey, @WebParam(name="commentTypeKey")String commentTypeKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 136 137 /** 138 * Retrieves tag information for a reference of a particular type. The expected behavior is that if the caller is not authorized to invoke the getTagsByType operation, a PERMISSION_DENIED error is returned. Assuming that the caller is authorized to invoke getTagsByType, only tags that the caller is authorized to view are included in the returned tagInfoList; tags that the caller is unauthorized to view are filtered out of the return parameter. 139 * @param referenceId reference identifier 140 * @param referenceTypeKey reference type 141 * @param tagTypeKey tag type 142 * @return list of tag information 143 * @throws DoesNotExistException specified referenceId, referenceTypeKey, tagTypeKey not found 144 * @throws InvalidParameterException invalid referenceId, referenceTypeKey,tagTypeKey 145 * @throws MissingParameterException referenceId, referenceTypeKey, tagTypeKey not specified 146 * @throws OperationFailedException unable to complete request 147 * @throws PermissionDeniedException authorization failure 148 */ 149 public List<TagInfo> getTagsByType(@WebParam(name="referenceId")String referenceId, @WebParam(name="referenceTypeKey")String referenceTypeKey, @WebParam(name="tagTypeKey")String tagTypeKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 150 151 /** 152 * Retrieves information about a comment. 153 * @param commentId comment identifier 154 * @return information about a comment 155 * @throws DoesNotExistException specified commentId not found 156 * @throws InvalidParameterException invalid commentId 157 * @throws MissingParameterException commentId not specified 158 * @throws OperationFailedException unable to complete request 159 * @throws PermissionDeniedException authorization failure 160 */ 161 public CommentInfo getComment(@WebParam(name="commentId")String commentId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 162 163 /** 164 * Retrieves information about a tag. 165 * @param tagId tag identifier 166 * @return information about a tag 167 * @throws DoesNotExistException specified tagId not found 168 * @throws InvalidParameterException invalid tagId 169 * @throws MissingParameterException tagId not specified 170 * @throws OperationFailedException unable to complete request 171 * @throws PermissionDeniedException authorization failure 172 */ 173 public TagInfo getTag(@WebParam(name="tagId")String tagId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 174 175 /** 176 * Adds a comment to a reference. 177 * @param referenceId identifier of reference 178 * @param referenceTypeKey reference type 179 * @param commentInfo detailed information about the comment 180 * @return detailed information about the comment 181 * @throws DataValidationErrorException One or more values invalid for this operation 182 * @throws InvalidParameterException One or more parameters invalid 183 * @throws MissingParameterException One or more parameters missing 184 * @throws OperationFailedException unable to complete request 185 * @throws PermissionDeniedException authorization failure 186 */ 187 public CommentInfo addComment(@WebParam(name="referenceId")String referenceId, @WebParam(name="referenceTypeKey")String referenceTypeKey, @WebParam(name="commentInfo")CommentInfo commentInfo) throws DataValidationErrorException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 188 189 /** 190 * Adds a tag to a reference. 191 * @param referenceId identifier of reference 192 * @param referenceTypeKey reference type 193 * @param tagInfo detailed information about the tag 194 * @return detailed information about the tag 195 * @throws DataValidationErrorException One or more values invalid for this operation 196 * @throws AlreadyExistsException tag of that namespace, predicate and value already exists for that reference id 197 * @throws InvalidParameterException One or more parameters invalid 198 * @throws MissingParameterException One or more parameters missing 199 * @throws OperationFailedException unable to complete request 200 * @throws PermissionDeniedException authorization failure 201 */ 202 public TagInfo addTag(@WebParam(name="referenceId")String referenceId, @WebParam(name="referenceTypeKey")String referenceTypeKey, @WebParam(name="tagInfo")TagInfo tagInfo) throws DataValidationErrorException, AlreadyExistsException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 203 204 /** 205 * Updates a comment for a reference. 206 * @param referenceId identifier of reference 207 * @param referenceTypeKey reference type 208 * @param commentInfo detailed information about the comment 209 * @return detailed information about the comment 210 * @throws DataValidationErrorException One or more values invalid for this operation 211 * @throws InvalidParameterException One or more parameters invalid 212 * @throws MissingParameterException One or more parameters missing 213 * @throws OperationFailedException unable to complete request 214 * @throws PermissionDeniedException authorization failure 215 * @throws DoesNotExistException comment does not exist 216 * @throws VersionMismatchException The action was attempted on an out of date version. * 217 */ 218 public CommentInfo updateComment(@WebParam(name="referenceId")String referenceId, @WebParam(name="referenceTypeKey")String referenceTypeKey, @WebParam(name="commentInfo")CommentInfo commentInfo) throws DataValidationErrorException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException, DoesNotExistException, VersionMismatchException; 219 220 /** 221 * Removes a comment from a reference. 222 * @param commentId identifier of the comment 223 * @param referenceId identifier of the reference 224 * @param referenceTypeKey reference type 225 * @return status of the operation (success, failed) 226 * @throws DoesNotExistException commentId, referenceId does not exist 227 * @throws InvalidParameterException One or more parameters invalid 228 * @throws MissingParameterException One or more parameters missing 229 * @throws OperationFailedException unable to complete request 230 * @throws PermissionDeniedException authorization failure 231 */ 232 public StatusInfo removeComment(@WebParam(name="commentId")String commentId, @WebParam(name="referenceId")String referenceId, @WebParam(name="referenceTypeKey")String referenceTypeKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 233 234 /** 235 * Removes a tag from a reference. 236 * @param tagId identifier of the tag 237 * @param referenceId identifier of the reference 238 * @param referenceTypeKey reference type 239 * @return status of the operation (success, failed) 240 * @throws DoesNotExistException tagId, referenceId does not exist 241 * @throws InvalidParameterException One or more parameters invalid 242 * @throws MissingParameterException One or more parameters missing 243 * @throws OperationFailedException unable to complete request 244 * @throws PermissionDeniedException authorization failure 245 */ 246 public StatusInfo removeTag(@WebParam(name="tagId")String tagId, @WebParam(name="referenceId")String referenceId, @WebParam(name="referenceTypeKey")String referenceTypeKey) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 247 248 /** 249 * Removes all comments associated with a single reference 250 * @param referenceId identifier of the reference 251 * @return status of the operation (success, failed) 252 * @throws DoesNotExistException referenceId does not exist 253 * @throws InvalidParameterException One or more parameters invalid 254 * @throws MissingParameterException One or more parameters missing 255 * @throws OperationFailedException unable to complete request 256 * @throws PermissionDeniedException authorization failure 257 */ 258 public StatusInfo removeComments(@WebParam(name="referenceId")String referenceId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 259 260 /** 261 * Removes a tag from all references to which it is linked. 262 * @param tagId identifier of the tag 263 * @return status of the operation (success, failed) 264 * @throws DoesNotExistException tagId does not exist 265 * @throws InvalidParameterException One or more parameters invalid 266 * @throws MissingParameterException One or more parameters missing 267 * @throws OperationFailedException unable to complete request 268 * @throws PermissionDeniedException authorization failure 269 */ 270 public StatusInfo removeTags(@WebParam(name="tagId")String tagId) throws DoesNotExistException, InvalidParameterException, MissingParameterException, OperationFailedException, PermissionDeniedException; 271 272 }