001/**
002 * Copyright 2014 Tampere University of Technology, Pori Department
003 * 
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 * 
008 *   http://www.apache.org/licenses/LICENSE-2.0
009 * 
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016package service.tut.pori.contentanalysis;
017
018import java.util.EnumSet;
019
020import service.tut.pori.contentanalysis.PhotoParameters.AnalysisType;
021import service.tut.pori.contentanalysis.CAContentCore.ServiceType;
022import core.tut.pori.http.RedirectResponse;
023import core.tut.pori.http.Response;
024import core.tut.pori.http.Response.Status;
025import core.tut.pori.http.annotations.HTTPAuthenticationParameter;
026import core.tut.pori.http.annotations.HTTPMethodParameter;
027import core.tut.pori.http.annotations.HTTPService;
028import core.tut.pori.http.annotations.HTTPServiceMethod;
029import core.tut.pori.http.parameters.AuthenticationParameter;
030import core.tut.pori.http.parameters.DataGroups;
031import core.tut.pori.http.parameters.InputStreamParameter;
032import core.tut.pori.http.parameters.IntegerParameter;
033import core.tut.pori.http.parameters.Limits;
034import core.tut.pori.http.parameters.LongParameter;
035import core.tut.pori.http.parameters.StringParameter;
036import core.tut.pori.utils.MediaUrlValidator.MediaType;
037import core.tut.pori.utils.XMLFormatter;
038
039
040/**
041 * This service enables content analysis and provides search features.
042 * 
043 * @see service.tut.pori.contentanalysis.reference.ClientService
044 * @see service.tut.pori.contentanalysis.reference.ServerService
045 */
046@HTTPService(name=Definitions.SERVICE_CA)
047public class ContentAnalysisService{
048  private static final EnumSet<MediaType> MEDIA_TYPES = EnumSet.of(MediaType.PHOTO);
049  private XMLFormatter _formatter = new XMLFormatter();
050
051  /**
052   * Returns photos that are associated with the given keywords.
053   * 
054   * @see service.tut.pori.contentanalysis.reference.ClientService#searchSimilarByKeyword(AuthenticationParameter, StringParameter, DataGroups, Limits, IntegerParameter, LongParameter)
055   * 
056   * @param authenticatedUser
057   * @param keywords
058   * @param dataGroups
059   * @param limits
060   * @param serviceIds
061   * @param userIdFilters
062   * @return response
063   */
064  @HTTPServiceMethod(name = Definitions.METHOD_SEARCH_SIMILAR_BY_KEYWORD, acceptedMethods={core.tut.pori.http.Definitions.METHOD_GET})
065  public Response searchSimilarByKeyword(
066      @HTTPAuthenticationParameter(required = false) AuthenticationParameter authenticatedUser,
067      @HTTPMethodParameter(name = Definitions.PARAMETER_KEYWORDS) StringParameter keywords, 
068      @HTTPMethodParameter(name = DataGroups.PARAMETER_DEFAULT_NAME, required = false) DataGroups dataGroups,
069      @HTTPMethodParameter(name = Limits.PARAMETER_DEFAULT_NAME, required = false) Limits limits,
070      @HTTPMethodParameter(name = Definitions.PARAMETER_SERVICE_ID, required = false) IntegerParameter serviceIds,
071      @HTTPMethodParameter(name = service.tut.pori.users.Definitions.PARAMETER_USER_ID, required = false) LongParameter userIdFilters
072      ) 
073  {
074    return new Response(CASearchCore.searchByKeyword(authenticatedUser.getUserIdentity(), keywords.getValues(), dataGroups, limits, ServiceType.fromIdArray(serviceIds.getValues()), userIdFilters.getValues()));
075  }
076
077  /**
078   * @see service.tut.pori.contentanalysis.reference.ClientService#updatePhotos(AuthenticationParameter, InputStreamParameter)
079   * 
080   * @param authenticatedUser
081   * @param xml
082   */
083  @HTTPServiceMethod(name = Definitions.METHOD_UPDATE_PHOTO_METADATA, acceptedMethods={core.tut.pori.http.Definitions.METHOD_POST})
084  public void updatePhotos(
085      @HTTPAuthenticationParameter AuthenticationParameter authenticatedUser,
086      @HTTPMethodParameter(name=InputStreamParameter.PARAMETER_DEFAULT_NAME, bodyParameter=true) InputStreamParameter xml
087      )
088  {
089    CAContentCore.updatePhotos(authenticatedUser.getUserIdentity(), _formatter.toObject(xml.getValue(), PhotoList.class));
090  }
091
092  /**
093   * @see service.tut.pori.contentanalysis.reference.ClientService#retrieveMediaObjects(AuthenticationParameter, DataGroups, Limits, IntegerParameter, StringParameter)
094   * 
095   * @param authenticatedUser
096   * @param dataGroups
097   * @param limits 
098   * @param serviceIds
099   * @param mediaObjectIds 
100   * @return response
101   */
102  @HTTPServiceMethod(name = Definitions.METHOD_RETRIEVE_MEDIA_OBJECTS, acceptedMethods={core.tut.pori.http.Definitions.METHOD_GET})
103  public Response retrieveMediaObjects(
104      @HTTPAuthenticationParameter(required = false) AuthenticationParameter authenticatedUser,
105      @HTTPMethodParameter(name = DataGroups.PARAMETER_DEFAULT_NAME, required = false) DataGroups dataGroups,
106      @HTTPMethodParameter(name = Limits.PARAMETER_DEFAULT_NAME, required = false) Limits limits,
107      @HTTPMethodParameter(name = Definitions.PARAMETER_SERVICE_ID, required = false) IntegerParameter serviceIds,
108      @HTTPMethodParameter(name = Definitions.PARAMETER_MEDIA_OBJECT_ID, required = false) StringParameter mediaObjectIds
109      )
110  {
111    return new Response(CAContentCore.getMediaObjects(authenticatedUser.getUserIdentity(), dataGroups, limits, MEDIA_TYPES, ServiceType.fromIdArray(serviceIds.getValues()), mediaObjectIds.getValues()));
112  }
113
114  /**
115   * @see service.tut.pori.contentanalysis.reference.ClientService#similarityFeedback(AuthenticationParameter, InputStreamParameter)
116   * 
117   * @param authenticatedUser
118   * @param xml 
119   */
120  @HTTPServiceMethod(name = Definitions.METHOD_SIMILARITY_FEEDBACK, acceptedMethods={core.tut.pori.http.Definitions.METHOD_POST})
121  public void similarityFeedback(
122      @HTTPAuthenticationParameter AuthenticationParameter authenticatedUser,
123      @HTTPMethodParameter(name = InputStreamParameter.PARAMETER_DEFAULT_NAME, bodyParameter = true) InputStreamParameter xml
124      )
125  {
126    CAContentCore.similarityFeedback(authenticatedUser.getUserIdentity(), _formatter.toObject(xml.getValue(), PhotoFeedbackList.class));
127  }
128
129  /**
130   * Returns photos that are similar with the photo associated with the given id.
131   * 
132   * @see service.tut.pori.contentanalysis.reference.ClientService#searchSimilarById(AuthenticationParameter, StringParameter, StringParameter, DataGroups, Limits, IntegerParameter, LongParameter)
133   * 
134   * @param authenticatedUser
135   * @param analysisType 
136   * @param guid
137   * @param dataGroups
138   * @param limits
139   * @param serviceIds
140   * @param userIdFilters
141   * @return response
142   */
143  @HTTPServiceMethod(name = Definitions.METHOD_SEARCH_SIMILAR_BY_ID, acceptedMethods={core.tut.pori.http.Definitions.METHOD_GET})
144  public Response searchSimilarById(
145      @HTTPAuthenticationParameter(required = false) AuthenticationParameter authenticatedUser, 
146      @HTTPMethodParameter(name = Definitions.PARAMETER_GUID) StringParameter guid,
147      @HTTPMethodParameter(name = Definitions.PARAMETER_ANALYSIS_TYPE, required = false) StringParameter analysisType,
148      @HTTPMethodParameter(name = DataGroups.PARAMETER_DEFAULT_NAME, required = false) DataGroups dataGroups,
149      @HTTPMethodParameter(name = Limits.PARAMETER_DEFAULT_NAME, required = false) Limits limits,
150      @HTTPMethodParameter(name = Definitions.PARAMETER_SERVICE_ID, required = false) IntegerParameter serviceIds,
151      @HTTPMethodParameter(name = service.tut.pori.users.Definitions.PARAMETER_USER_ID, required = false) LongParameter userIdFilters
152      ) 
153  {
154    return new Response(CASearchCore.searchByGUID(authenticatedUser.getUserIdentity(), AnalysisType.fromAnalysisTypeString(analysisType.getValues()), guid.getValue(), dataGroups, limits, ServiceType.fromIdArray(serviceIds.getValues()), userIdFilters.getValues()));
155  }
156
157  /**
158   * @see service.tut.pori.contentanalysis.reference.ClientService#searchSimilarByContent(AuthenticationParameter, StringParameter, StringParameter, DataGroups, Limits, IntegerParameter, LongParameter)
159   * 
160   * @param authenticatedUser
161   * @param analysisType 
162   * @param url
163   * @param dataGroups
164   * @param limits
165   * @param serviceIds
166   * @param userIdFilters
167   * @return response
168   */
169  @HTTPServiceMethod(name = Definitions.METHOD_SEARCH_SIMILAR_BY_CONTENT, acceptedMethods={core.tut.pori.http.Definitions.METHOD_GET})
170  public Response searchSimilarByContent(
171      @HTTPAuthenticationParameter(required = false) AuthenticationParameter authenticatedUser,
172      @HTTPMethodParameter(name = Definitions.PARAMETER_ANALYSIS_TYPE, required = false) StringParameter analysisType, 
173      @HTTPMethodParameter(name = Definitions.PARAMETER_URL) StringParameter url, 
174      @HTTPMethodParameter(name = DataGroups.PARAMETER_DEFAULT_NAME, required = false) DataGroups dataGroups, 
175      @HTTPMethodParameter(name = Limits.PARAMETER_DEFAULT_NAME, required = false) Limits limits,
176      @HTTPMethodParameter(name = Definitions.PARAMETER_SERVICE_ID, required = false) IntegerParameter serviceIds, 
177      @HTTPMethodParameter(name = service.tut.pori.users.Definitions.PARAMETER_USER_ID, required = false) LongParameter userIdFilters
178      ) 
179  {  
180    return new Response(CASearchCore.searchByContent(authenticatedUser.getUserIdentity(), AnalysisType.fromAnalysisTypeString(analysisType.getValues()), url.getValue(), dataGroups, limits, ServiceType.fromIdArray(serviceIds.getValues()), userIdFilters.getValues()));
181  }
182
183  /**
184   * @see service.tut.pori.contentanalysis.reference.ServerService#queryTaskDetails(IntegerParameter, LongParameter, DataGroups, Limits)
185   * 
186   * @param taskId
187   * @param backendId
188   * @param dataGroups
189   * @param limits
190   * @return response
191   */
192  @HTTPServiceMethod(name = Definitions.METHOD_QUERY_TASK_DETAILS, acceptedMethods={core.tut.pori.http.Definitions.METHOD_GET})
193  public Response queryTaskDetails(
194      @HTTPMethodParameter(name = Definitions.PARAMETER_BACKEND_ID) IntegerParameter backendId,
195      @HTTPMethodParameter(name = Definitions.PARAMETER_TASK_ID) LongParameter taskId,
196      @HTTPMethodParameter(name = DataGroups.PARAMETER_DEFAULT_NAME, required = false) DataGroups dataGroups,
197      @HTTPMethodParameter(name = Limits.PARAMETER_DEFAULT_NAME, required = false) Limits limits
198      ) 
199  {
200    AbstractTaskDetails details = CAContentCore.queryTaskDetails(backendId.getValue(), taskId.getValue(), dataGroups, limits);
201    if(details == null){
202      return new Response(Status.BAD_REQUEST, "Invalid "+Definitions.PARAMETER_TASK_ID+" or "+Definitions.PARAMETER_BACKEND_ID+".");
203    }else{
204      return new Response(details);
205    }
206  }
207
208  /**
209   * @see service.tut.pori.contentanalysis.reference.ServerService#taskFinished(InputStreamParameter)
210   * 
211   * @param xml
212   */
213  @HTTPServiceMethod(name = Definitions.METHOD_TASK_FINISHED, acceptedMethods={core.tut.pori.http.Definitions.METHOD_POST})
214  public void taskFinished(@HTTPMethodParameter(name = InputStreamParameter.PARAMETER_DEFAULT_NAME, bodyParameter = true) InputStreamParameter xml) {
215    CAContentCore.taskFinished(_formatter.toObject(xml.getValue(), PhotoTaskResponse.class));
216  }
217
218  /**
219   * @see service.tut.pori.contentanalysis.reference.ClientService#getPhotos(AuthenticationParameter, StringParameter, DataGroups, Limits, IntegerParameter, LongParameter)
220   * 
221   * @param authenticatedUser
222   * @param guid
223   * @param dataGroups
224   * @param limits
225   * @param serviceIds
226   * @param userIds 
227   * @return response
228   */
229  @HTTPServiceMethod(name = Definitions.METHOD_RETRIEVE_PHOTO_METADATA, acceptedMethods={core.tut.pori.http.Definitions.METHOD_GET})
230  public Response getPhotos(
231      @HTTPAuthenticationParameter(required = false) AuthenticationParameter authenticatedUser,
232      @HTTPMethodParameter(name = Definitions.PARAMETER_GUID, required = false) StringParameter guid,
233      @HTTPMethodParameter(name = DataGroups.PARAMETER_DEFAULT_NAME, required = false) DataGroups dataGroups,
234      @HTTPMethodParameter(name = Limits.PARAMETER_DEFAULT_NAME, required = false) Limits limits,
235      @HTTPMethodParameter(name = Definitions.PARAMETER_SERVICE_ID, required = false) IntegerParameter serviceIds,
236      @HTTPMethodParameter(name = service.tut.pori.users.Definitions.PARAMETER_USER_ID, required = false) LongParameter userIds
237      )
238  {
239    return new Response(CAContentCore.getPhotos(authenticatedUser.getUserIdentity(), guid.getValues(), dataGroups, limits, ServiceType.fromIdArray(serviceIds.getValues()), userIds.getValues()));
240  }
241
242  /**
243   * @see service.tut.pori.contentanalysis.reference.ClientService#similarPhotosByObject(AuthenticationParameter, DataGroups, Limits, IntegerParameter, LongParameter, InputStreamParameter)
244   * 
245   * @param authenticatedUser
246   * @param dataGroups
247   * @param limits
248   * @param serviceIds
249   * @param userIdFilters
250   * @param xml
251   * @return response
252   */
253  @HTTPServiceMethod(name = Definitions.METHOD_SEARCH_SIMILAR_BY_OBJECT, acceptedMethods={core.tut.pori.http.Definitions.METHOD_POST})
254  public Response similarPhotosByObject(
255      @HTTPAuthenticationParameter(required = false) AuthenticationParameter authenticatedUser,
256      @HTTPMethodParameter(name = DataGroups.PARAMETER_DEFAULT_NAME, required = false) DataGroups dataGroups,
257      @HTTPMethodParameter(name = Limits.PARAMETER_DEFAULT_NAME, required = false) Limits limits,
258      @HTTPMethodParameter(name = Definitions.PARAMETER_SERVICE_ID, required = false) IntegerParameter serviceIds,
259      @HTTPMethodParameter(name = service.tut.pori.users.Definitions.PARAMETER_USER_ID, required = false) LongParameter userIdFilters,
260      @HTTPMethodParameter(name = InputStreamParameter.PARAMETER_DEFAULT_NAME, bodyParameter = true) InputStreamParameter xml
261      )
262  {
263    return new Response(CASearchCore.similarPhotosByObject(authenticatedUser.getUserIdentity(), _formatter.toObject(xml.getValue(), MediaObjectList.class), dataGroups, limits, ServiceType.fromIdArray(serviceIds.getValues()), userIdFilters.getValues()));
264  }
265
266  /**
267   * @see service.tut.pori.contentanalysis.reference.ClientService#r(AuthenticationParameter, IntegerParameter, StringParameter)
268   * 
269   * @param authenticatedUser
270   * @param serviceId
271   * @param guid
272   * @return response
273   */
274  @HTTPServiceMethod(name = Definitions.METHOD_REDIRECT, acceptedMethods={core.tut.pori.http.Definitions.METHOD_GET})
275  public RedirectResponse r(
276      @HTTPAuthenticationParameter(required = false) AuthenticationParameter authenticatedUser,
277      @HTTPMethodParameter(name = Definitions.PARAMETER_SERVICE_ID) IntegerParameter serviceId,
278      @HTTPMethodParameter(name = Definitions.PARAMETER_GUID) StringParameter guid
279      )
280  {
281    return CAContentCore.generateTargetUrl(authenticatedUser.getUserIdentity(), ServiceType.fromServiceId(serviceId.getValue()), guid.getValue());
282  }
283  
284  /**
285   * @see service.tut.pori.contentanalysis.reference.ClientService#deletePhotos(AuthenticationParameter, StringParameter)
286   * 
287   * @param authenticatedUser
288   * @param guid
289   * @return response
290   */
291  @HTTPServiceMethod(name = Definitions.METHOD_DELETE_PHOTO_METADATA, acceptedMethods={core.tut.pori.http.Definitions.METHOD_DELETE})
292  public Response deletePhotos(
293      @HTTPAuthenticationParameter AuthenticationParameter authenticatedUser,
294      @HTTPMethodParameter(name = Definitions.PARAMETER_GUID) StringParameter guid
295      )
296  {
297    return (CAContentCore.deletePhotos(authenticatedUser.getUserIdentity(), guid.getValues()) ? new Response() : new Response(Status.FORBIDDEN));
298  }
299}