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 core.tut.pori.http.annotations;
017
018import static java.lang.annotation.ElementType.METHOD;
019import static java.lang.annotation.RetentionPolicy.RUNTIME;
020
021import java.lang.annotation.Documented;
022import java.lang.annotation.Inherited;
023import java.lang.annotation.Retention;
024import java.lang.annotation.Target;
025
026import core.tut.pori.http.Definitions;
027
028
029/**
030 * The objects returned by the method MUST BE of type or inherited type of core.tut.pori.http.Response or void if default Response is to be used
031 *
032 * Note: Your web services MUST be thread-safe and re-entrant
033 * 
034 * The methods are mapped based on the method name (name()) and the accepted methods (acceptedMethods()).
035 * The name-method pairs must be unique:
036 * <ul>
037 *  <li>for the a single method with a name NAME there can be methods GET and POST, or</li>
038 *  <li>two separate methods can both have the name NAME if and only if their methods do not contain same method names (i.e. method 1 can have method name GET, and method 2 can have method name POST, but not GET)</li>
039 *  <li>the method name does not have to be one specified in RFC2616 (or, as defined by the document) can be any valid String</li>
040 * </ul>
041 * 
042 * Example 1:
043 * 
044 * \@HTTPServiceMethod(name="TEST", acceptedMethods={"GET"})<br>
045 * public Response function1( ... ){ ... }
046 * 
047 * \@HTTPServiceMethod(name="TEST",acceptedMethods={"POST"})<br>
048 * public Response function2( ... ){ ... }
049 * 
050 * <ul>
051 *  <li>In this example, the calls for method TEST will be directed to function1 when HTTP GET is performed, and to function2 when HTTP POST is performed</li>
052 *  <li>Note that function1 and function2 are separate functions, and will be treated as such, and can have different signatures (e.g. parameters)</li>
053 * </ul> 
054 *  
055 *  
056 *  Example 2:
057 *  
058 *  \@HTTPServiceMethod(name="TEST", acceptedMethods={"GET","POST"})<br>
059 *  public Response function1( ... ){ ... }
060 *  
061 *  <ul><li>In this example, the calls for method TEST with HTTP GET or HTTP POST will both be directed to function1</li></ul>
062 *  
063 *  The method will be reachable in the path designated by the \@HTTPService annotation's name and this annotation's name, generally in the format /WebApplicationName/rest/SERVICE_NAME/METHOD_NAME
064 */
065@Retention(RUNTIME)
066@Target({METHOD})
067@Inherited
068@Documented
069public @interface HTTPServiceMethod {
070  /**
071   * Name for the method
072   * 
073   * @return method name
074   */
075  String name();
076  
077  /**
078   * 
079   * @return accepted HTTP Methods for this service method
080   */
081  String[] acceptedMethods() default {Definitions.METHOD_GET,Definitions.METHOD_POST};
082}