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.twitterjazz.reference;
017
018import java.io.IOException;
019import java.io.InputStream;
020
021import org.apache.commons.io.IOUtils;
022import org.apache.log4j.Logger;
023
024import service.tut.pori.contentanalysis.Definitions;
025import service.tut.pori.contentanalysis.PhotoTaskResponse;
026import service.tut.pori.twitterjazz.TwitterTaskResponse;
027import core.tut.pori.http.annotations.HTTPMethodParameter;
028import core.tut.pori.http.annotations.HTTPService;
029import core.tut.pori.http.annotations.HTTPServiceMethod;
030import core.tut.pori.http.parameters.InputStreamParameter;
031import core.tut.pori.utils.XMLFormatter;
032
033/**
034 * 
035 * Reference implementation for Server APIs. This class defines the APIs offered by the Front-end to Analysis Back-ends.
036 *
037 * <h1>Implementation Service path {@value service.tut.pori.twitterjazz.Definitions#SERVICE_TJ}</h1>
038 * 
039 * @see service.tut.pori.twitterjazz.TwitterJazzService
040 */
041@HTTPService(name = service.tut.pori.twitterjazz.reference.Definitions.SERVICE_TJ_REFERENCE_SERVER)
042public class ServerService {
043  private static final Logger LOGGER = Logger.getLogger(ServerService.class);
044  private XMLFormatter _formatter = new XMLFormatter();
045  
046  /**
047   * The request is to be sent in the body of POST method. The Content-Type header MUST be set to "text/xml". The character set MUST be UTF-8. For example, "Content-Type: text/xml; charset=UTF-8".
048   * 
049   * The method can be called multiple times by the back-ends. Each call is assumed to be an incremental update on the previous one and can contain any amount of new information. 
050   * It is also possible to update previously submitted data by using the same identifiers: photo GUID (for photos), and media object id or a combination of back-end id and object id (for media objects).
051   * 
052   * Task results may contain photo specific back-end status information, though it is not required.
053   * 
054   * Using an invalid back-end id (both for the task and the generated media objects) can result in an error, causing the entire task result to be rejected. It is not allowed for a one back-end to update/modify media objects previously submitted by another back-end, or by the user.
055   * 
056   * <h2>Example Query:</h2>
057   *
058   * POST /rest/{@value service.tut.pori.twitterjazz.reference.Definitions#SERVICE_TJ_REFERENCE_SERVER}/{@value service.tut.pori.contentanalysis.Definitions#METHOD_TASK_FINISHED}<br>
059   * Content-Type: text/xml; charset=UTF-8<br><br>
060   *
061   * <b>[HTTP BODY STARTS]</b><br>
062   * 
063   * {@doc.restlet service="[service.tut.pori.twitterjazz.reference.Definitions#SERVICE_TJ_REFERENCE_EXAMPLE]" method="[service.tut.pori.contentanalysis.Definitions#ELEMENT_TASK_RESULTS]" type="GET" query="" body_uri=""} <br>
064   * 
065   * <b>[HTTP BODY ENDS]</b><br>
066   *
067   * <h2>Example Result:</h2>
068   * 
069   * {@doc.restlet service="[service.tut.pori.twitterjazz.reference.Definitions#SERVICE_TJ_REFERENCE_SERVER]" method="[service.tut.pori.contentanalysis.Definitions#METHOD_TASK_FINISHED]" type="POST" query="" body_uri="[service.tut.pori.twitterjazz.reference.Definitions#SERVICE_TJ_REFERENCE_EXAMPLE]/[service.tut.pori.contentanalysis.Definitions#ELEMENT_TASK_RESULTS]"}
070   * 
071   * @param xml The HTTP body. Only the result data should be in the body. See {@link service.tut.pori.twitterjazz.TwitterTaskResponse}
072   */
073  @HTTPServiceMethod(name = Definitions.METHOD_TASK_FINISHED, acceptedMethods={core.tut.pori.http.Definitions.METHOD_POST})
074  public void taskFinished(@HTTPMethodParameter(name = InputStreamParameter.PARAMETER_DEFAULT_NAME, bodyParameter = true) InputStreamParameter xml) {
075    try {
076      String body = IOUtils.toString(xml.getValue()); // read the body
077      LOGGER.debug(body); // print to debug
078      try(InputStream input = IOUtils.toInputStream(body)){ // convert back to stream for unmarshal
079        TJReferenceCore.taskFinished(_formatter.toObject(input, TwitterTaskResponse.class, PhotoTaskResponse.class));
080      }
081    } catch (IOException ex) {
082      LOGGER.error(ex, ex);
083    }
084  }
085}