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.facebookjazz.reference;
017
018import service.tut.pori.facebookjazz.Definitions;
019import service.tut.pori.facebookjazz.WeightModifierList;
020import core.tut.pori.http.Response;
021import core.tut.pori.http.annotations.HTTPAuthenticationParameter;
022import core.tut.pori.http.annotations.HTTPMethodParameter;
023import core.tut.pori.http.annotations.HTTPService;
024import core.tut.pori.http.annotations.HTTPServiceMethod;
025import core.tut.pori.http.parameters.AuthenticationParameter;
026import core.tut.pori.http.parameters.BooleanParameter;
027import core.tut.pori.http.parameters.DataGroups;
028import core.tut.pori.http.parameters.InputStreamParameter;
029import core.tut.pori.http.parameters.Limits;
030import core.tut.pori.http.parameters.LongParameter;
031import core.tut.pori.http.parameters.SortOptions;
032import core.tut.pori.http.parameters.StringParameter;
033import core.tut.pori.utils.XMLFormatter;
034
035/**
036 * Reference implementation for client API methods.
037 * 
038 * <h1>Implementation Service path {@value service.tut.pori.facebookjazz.Definitions#SERVICE_FBJ}</h1>
039 * 
040 * @see service.tut.pori.facebookjazz.FacebookJazzService
041 *
042 */
043@HTTPService(name = service.tut.pori.facebookjazz.reference.Definitions.SERVICE_FBJ_REFERENCE_CLIENT)
044public class ClientService {
045  private XMLFormatter _formatter = new XMLFormatter();
046  /**
047   * Clients can use this method for retrieving a list of tags extracted by the profile summarization. This will always return the tags for the currently authenticated user.
048   * 
049   * <h2>Example Query:</h2>
050   *
051   * GET /rest/{@value service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_CLIENT}/{@value service.tut.pori.facebookjazz.Definitions#METHOD_RETRIEVE_TAGS_FOR_USER}<br>
052   *
053   * <h2>Example Result:</h2>
054   * 
055   * {@doc.restlet service="[service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_CLIENT]" method="[service.tut.pori.facebookjazz.Definitions#METHOD_RETRIEVE_TAGS_FOR_USER]" type="GET" query="" body_uri=""}
056   * 
057   * @param authenticatedUser This method requires user authentication. The user must have authorized the use of his/her Facebook account. Note: this method requires authentication, but for the reference implementation, anonymous access is granted.
058   * @param sortOptions supported element names are {@value service.tut.pori.contentanalysis.Definitions#ELEMENT_CONFIDENCE}, {@value service.tut.pori.contentanalysis.Definitions#ELEMENT_RANK} and {@value service.tut.pori.contentanalysis.Definitions#ELEMENT_VALUE}. Default sorting order is the original addition order of the objects.
059   * @param dataGroups For supported data groups see {@link service.tut.pori.contentanalysis.reference.ClientService#retrieveMediaObjects(AuthenticationParameter, DataGroups, Limits, core.tut.pori.http.parameters.IntegerParameter, StringParameter)}.
060   * @param limits paging limits
061   * @return See {@link service.tut.pori.contentanalysis.MediaObjectList}
062   */
063  @HTTPServiceMethod(name = Definitions.METHOD_RETRIEVE_TAGS_FOR_USER, acceptedMethods={core.tut.pori.http.Definitions.METHOD_GET})
064  public Response retrieveTagsForUser(
065      @HTTPAuthenticationParameter(required=false) AuthenticationParameter authenticatedUser,
066      @HTTPMethodParameter(name = DataGroups.PARAMETER_DEFAULT_NAME, required = false) DataGroups dataGroups,
067      @HTTPMethodParameter(name = Limits.PARAMETER_DEFAULT_NAME, required = false) Limits limits,
068      @HTTPMethodParameter(name = service.tut.pori.contentanalysis.Definitions.PARAMETER_SORT, required = false) SortOptions sortOptions
069      )
070  {
071    return new Response(FBJReferenceCore.retrieveTagsForUser(authenticatedUser.getUserIdentity(), dataGroups, limits, sortOptions));
072  }
073  
074  /**
075   * Clients can use this method for ranking (rating) tags.
076   * 
077   * <h2>Example Query:</h2>
078   *
079   * GET /rest/{@value service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_CLIENT}/{@value service.tut.pori.facebookjazz.Definitions#METHOD_SET_RANK}?{@value service.tut.pori.facebookjazz.Definitions#PARAMETER_RANK}=1;100,2;-10<br>
080   *
081   * <h2>Example Result:</h2>
082   * 
083   * {@doc.restlet service="[service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_CLIENT]" method="[service.tut.pori.facebookjazz.Definitions#METHOD_SET_RANK]" type="POST" query="[service.tut.pori.facebookjazz.Definitions#PARAMETER_RANK]=1;100,2;-10" body_uri=""}
084   * 
085   * @param authenticatedUser This method requires user authentication. The user must have authorized the use of his/her Facebook account. Note: this method requires authentication, but for the reference implementation, anonymous access is granted.
086   * @param ranks with format {@value service.tut.pori.facebookjazz.Definitions#PARAMETER_RANK}={@value service.tut.pori.contentanalysis.Definitions#ELEMENT_MEDIA_OBJECT_ID}{@value core.tut.pori.http.Definitions#SEPARATOR_URI_QUERY_TYPE_VALUE}VALUE{@value core.tut.pori.http.Definitions#SEPARATOR_URI_QUERY_PARAM_VALUES}{@value service.tut.pori.contentanalysis.Definitions#ELEMENT_MEDIA_OBJECT_ID}{@value core.tut.pori.http.Definitions#SEPARATOR_URI_QUERY_TYPE_VALUE}VALUE{@value core.tut.pori.http.Definitions#SEPARATOR_URI_QUERY_PARAM_VALUES} ...
087   */
088  @HTTPServiceMethod(name = Definitions.METHOD_SET_RANK, acceptedMethods={core.tut.pori.http.Definitions.METHOD_POST})
089  public void setRank(
090      @HTTPAuthenticationParameter(required=false) AuthenticationParameter authenticatedUser,
091      @HTTPMethodParameter(name = Definitions.PARAMETER_RANK) StringParameter ranks)
092  {
093    FBJReferenceCore.setRank(authenticatedUser.getUserIdentity(), ranks.getValues());
094  }
095  
096  /**
097   * Clients can use this method for retrieving tag weight modifiers.
098   * 
099   * <h2>Example Query:</h2>
100   *
101   * GET /rest/{@value service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_CLIENT}/{@value service.tut.pori.facebookjazz.Definitions#METHOD_RETRIEVE_TAG_WEIGHTS}<br>
102   *
103   * <h2>Example Result:</h2>
104   * 
105   * {@doc.restlet service="[service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_CLIENT]" method="[service.tut.pori.facebookjazz.Definitions#METHOD_RETRIEVE_TAG_WEIGHTS]" type="GET" query="" body_uri=""}
106   *  
107   * @param authenticatedUser This method requires user authentication. The user must have authorized the use of his/her Facebook account. Note: this method requires authentication, but for the reference implementation, anonymous access is granted.
108   * @param userIdFilter User id filter, if not given the default tag weights will be returned.
109   * @return See {@link service.tut.pori.facebookjazz.WeightModifierList}
110   */
111  @HTTPServiceMethod(name = Definitions.METHOD_RETRIEVE_TAG_WEIGHTS, acceptedMethods={core.tut.pori.http.Definitions.METHOD_GET})
112  public Response retrieveTagWeights(
113      @HTTPAuthenticationParameter(required = false) AuthenticationParameter authenticatedUser,
114      @HTTPMethodParameter(name = service.tut.pori.users.Definitions.PARAMETER_USER_ID, required = false) LongParameter userIdFilter
115      )
116  {
117    return new Response(FBJReferenceCore.retrieveTagWeights(authenticatedUser.getUserIdentity(), userIdFilter.getValue()));
118  }
119  
120  /**
121   * Clients can use this method to set tag weights.
122   * 
123   * POST /rest/{@value service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_CLIENT}/{@value service.tut.pori.facebookjazz.Definitions#METHOD_SET_TAG_WEIGHTS}<br>
124   * Content-Type: text/xml; charset=UTF-8<br><br>
125   *
126   * <b>[HTTP BODY STARTS]</b><br>
127   * 
128   * {@doc.restlet service="[service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_EXAMPLE]" method="[service.tut.pori.facebookjazz.Definitions#ELEMENT_WEIGHT_MODIFIER_LIST]" type="GET" query="" body_uri=""} <br>
129   * 
130   * <b>[HTTP BODY ENDS]</b><br>
131   *
132   * <h2>Example Result:</h2>
133   * 
134   * {@doc.restlet service="[service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_CLIENT]" method="[service.tut.pori.facebookjazz.Definitions#METHOD_SET_TAG_WEIGHTS]" type="POST" query="" body_uri="[service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_EXAMPLE]/[service.tut.pori.facebookjazz.Definitions#ELEMENT_WEIGHT_MODIFIER_LIST]"}
135   * 
136   * @param authenticatedUser This method requires user authentication. The user must have authorized the use of his/her Facebook account. Note: this method requires authentication, but for the reference implementation, anonymous access is granted.
137   * @param xml The tag weight modifiers for the user. See {@link service.tut.pori.facebookjazz.WeightModifierList}
138   */
139  @HTTPServiceMethod(name = Definitions.METHOD_SET_TAG_WEIGHTS, acceptedMethods={core.tut.pori.http.Definitions.METHOD_POST})
140  public void setTagWeights(
141      @HTTPAuthenticationParameter(required = false) AuthenticationParameter authenticatedUser,
142      @HTTPMethodParameter(name = InputStreamParameter.PARAMETER_DEFAULT_NAME, bodyParameter = true) InputStreamParameter xml
143      )
144  {
145    FBJReferenceCore.setTagWeights(authenticatedUser.getUserIdentity(), _formatter.toObject(xml.getValue(), WeightModifierList.class));
146  }
147  
148  /**
149   * Clients can use this method to initialize account summarization, and optionally perform synchronization for photo content.
150   * 
151   * <h2>Example Query:</h2>
152   *
153   * GET /rest/{@value service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_CLIENT}/{@value service.tut.pori.facebookjazz.Definitions#METHOD_SUMMARIZE}<br>
154   *
155   * <h2>Example Result:</h2>
156   * 
157   * {@doc.restlet service="[service.tut.pori.facebookjazz.reference.Definitions#SERVICE_FBJ_REFERENCE_CLIENT]" method="[service.tut.pori.facebookjazz.Definitions#METHOD_SUMMARIZE]" type="GET" query="" body_uri=""}
158   * 
159   * @param authenticatedUser This method requires user authentication. The user must have authorized the use of his/her Facebook account. Note: this method requires authentication, but for the reference implementation, anonymous access is granted.
160   * @param contentTypes Any combination of content types. Valid types are: events, generated_tags, groups, likes, photo_descriptions, status_messages, video_descriptions. See {@link service.tut.pori.facebookjazz.FacebookExtractor.ContentType}
161   * @param synchronize On <i>true</i> synchronizes the photo content of the user's account prior to starting the summarization process. Photo analysis tasks will be created for new content using default analysis back-ends.
162   */
163  @HTTPServiceMethod(name = Definitions.METHOD_SUMMARIZE)
164  public void summarize(
165      @HTTPAuthenticationParameter(required=false) AuthenticationParameter authenticatedUser,
166      @HTTPMethodParameter(name = Definitions.PARAMETER_CONTENT_TYPES, required = false) StringParameter contentTypes,
167      @HTTPMethodParameter(name = Definitions.PARAMETER_SYNCHRONIZE, required = false) BooleanParameter synchronize)
168  {
169    FBJReferenceCore.summarize(authenticatedUser.getUserIdentity(), contentTypes.getValues(), synchronize.isTrue());
170  }
171}