001/**
002 * Copyright 2015 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.contentsuggest.reference;
017
018import service.tut.pori.contentsuggest.Definitions;
019import core.tut.pori.http.Response;
020import core.tut.pori.http.annotations.HTTPAuthenticationParameter;
021import core.tut.pori.http.annotations.HTTPMethodParameter;
022import core.tut.pori.http.annotations.HTTPService;
023import core.tut.pori.http.annotations.HTTPServiceMethod;
024import core.tut.pori.http.parameters.AuthenticationParameter;
025import core.tut.pori.http.parameters.DataGroups;
026import core.tut.pori.http.parameters.Limits;
027import core.tut.pori.http.parameters.StringParameter;
028
029/**
030 * Reference implementation for client API methods.
031 * 
032 * <h1>Implementation Service path {@value service.tut.pori.contentsuggest.Definitions#SERVICE_CS}</h1>
033 * 
034 * @see service.tut.pori.contentsuggest.ContentSuggestService
035 */
036@HTTPService(name = service.tut.pori.contentsuggest.reference.Definitions.SERVICE_CS_REFERENCE_CLIENT)
037public class ClientService {
038  /**
039   * This method is for retrieving a list of suggestions based on the indexed data of the user. The data can include content be generated by any back-end, by the authenticated user, and can also include public content created by other users.
040   * 
041   * This method can be used to provide general content suggestions, or it can be used to implement auto-complete functionality to be used, for example, with search fields in web applications.
042   * 
043   * <h2>Example Query:</h2>
044   *
045   * GET /rest/{@value service.tut.pori.contentsuggest.reference.Definitions#SERVICE_CS_REFERENCE_CLIENT}/{@value service.tut.pori.contentsuggest.Definitions#METHOD_SUGGEST}?{@value service.tut.pori.contentsuggest.Definitions#PARAMETER_QUERY}=peter<br>
046   *
047   * <h2>Example Result:</h2>
048   * 
049   * {@doc.restlet service="[service.tut.pori.contentsuggest.reference.Definitions#SERVICE_CS_REFERENCE_CLIENT]" method="[service.tut.pori.contentsuggest.Definitions#METHOD_SUGGEST]" type="GET" query="[service.tut.pori.contentsuggest.Definitions#PARAMETER_QUERY]=peter" body_uri=""}
050   * 
051   * @param authenticatedUser Note: this method requires authentication, but for the reference implementation, anonymous access is granted.
052   * @param dataGroups filters based on {@link service.tut.pori.contentanalysis.MediaObject.MediaObjectType}. Applicable values are {@value service.tut.pori.contentanalysis.Definitions#DATA_GROUP_FACE}, {@value service.tut.pori.contentanalysis.Definitions#DATA_GROUP_KEYWORDS}, {@value service.tut.pori.contentanalysis.Definitions#DATA_GROUP_METADATA} and {@value service.tut.pori.contentanalysis.Definitions#DATA_GROUP_OBJECT}.
053   * @param query The query string for a suggestion. The query string is tokenized with character "{@value service.tut.pori.contentsuggest.Definitions#QUERY_SEPARATOR}", and the last token is sent to the suggestion back-end. 
054   * @param limits paging limits
055   * @return See {@link service.tut.pori.contentsuggest.AutoCompleteResult}
056   */
057  @HTTPServiceMethod(name = Definitions.METHOD_SUGGEST, acceptedMethods={core.tut.pori.http.Definitions.METHOD_GET})
058  public Response suggest(
059      @HTTPAuthenticationParameter(required=false) AuthenticationParameter authenticatedUser,
060      @HTTPMethodParameter(name = DataGroups.PARAMETER_DEFAULT_NAME, required = false) DataGroups dataGroups,
061      @HTTPMethodParameter(name = Definitions.PARAMETER_QUERY, required = true) StringParameter query,
062      @HTTPMethodParameter(name = Limits.PARAMETER_DEFAULT_NAME, required = false, defaultValue=Definitions.DEFAULT_LIMITS) Limits limits)
063  {
064    return new Response(ContentSuggestReferenceCore.suggest(authenticatedUser.getUserIdentity(), dataGroups, limits, query.getValue()));
065  }
066}