Skip to content

Commit 4782792

Browse files
DaySDayS
committed
Update javadoc for Rest annotations
1 parent 62daabd commit 4782792

File tree

14 files changed

+661
-8
lines changed

14 files changed

+661
-8
lines changed

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/rest/Accept.java‎

Lines changed: 38 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,44 @@
2020
import java.lang.annotation.RetentionPolicy;
2121
import java.lang.annotation.Target;
2222

23+
import org.androidannotations.api.rest.MediaType;
24+
25+
/**
26+
* Use on {@link Get}, {@link Post}, … annotated methods to negotiate the
27+
* response format expected, and so the converter to use.
28+
* <p/>
29+
* The annotation {@link #value()} is mandatory and define the <a
30+
* href="https://en.wikipedia.org/wiki/Internet_media_type">media type</a> to
31+
* accept. We provide a {@link MediaType} class to help you.
32+
* <p/>
33+
* <blockquote>
34+
*
35+
* <b>Example :</b>
36+
*
37+
* <pre>
38+
* &#064;Rest(rootUrl = &quot;http://myserver&quot;, converters = { MappingJacksonHttpMessageConverter.class, SimpleXmlHttpMessageConverter.class })
39+
* public interface MyRestClient {
40+
*
41+
* &#064;Get(&quot;/events/{id}&quot;)
42+
* &#064;Accept(<b>MediaType.APPLICATION_JSON</b>)
43+
* Event getEvent(long id);
44+
*
45+
* &#064;Post(&quot;/entity&quot;)
46+
* &#064;Accept(<b>MediaType.APPLICATION_XML</b>)
47+
* Event addEvent(Event event);
48+
* }
49+
* </pre>
50+
*
51+
* </blockquote>
52+
*
53+
* @see Rest
54+
* @see Get
55+
* @see Post
56+
* @see Put
57+
* @see Delete
58+
* @see Head
59+
* @see Options
60+
*/
2361
@Retention(RetentionPolicy.CLASS)
2462
@Target({ ElementType.METHOD, ElementType.TYPE })
2563
public @interface Accept {

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/rest/Delete.java‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,37 @@
2020
import java.lang.annotation.RetentionPolicy;
2121
import java.lang.annotation.Target;
2222

23+
/**
24+
* Use on methods in {@link Rest} annotated class to add a new rest service of
25+
* type DELETE.
26+
* <p/>
27+
* This annotation as the EXACT same constraints as {@link Post}.
28+
* <p/>
29+
* <blockquote>
30+
*
31+
* <b>Example :</b>
32+
*
33+
* <pre>
34+
* &#064;Rest(rootUrl = &quot;http://myserver&quot;, converters = MappingJacksonHttpMessageConverter.class)
35+
* public interface MyRestClient {
36+
*
37+
* &#064;Delete(&quot;/events/delete/last&quot;)
38+
* Event deleteEvent();
39+
*
40+
* &#064;Delete(&quot;/events/new/<b>{id}</b>&quot;)
41+
* void deleteEvent(Event <i>event</i>, int <b>id</b>);
42+
* }
43+
* </pre>
44+
*
45+
* </blockquote>
46+
*
47+
* @see Rest
48+
* @see Get
49+
* @see Post
50+
* @see Put
51+
* @see Head
52+
* @see Options
53+
*/
2354
@Retention(RetentionPolicy.CLASS)
2455
@Target(ElementType.METHOD)
2556
public @interface Delete {

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/rest/Get.java‎

Lines changed: 47 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,53 @@
2020
import java.lang.annotation.RetentionPolicy;
2121
import java.lang.annotation.Target;
2222

23+
/**
24+
* Use on methods in {@link Rest} annotated class to add a new rest service of
25+
* type GET.
26+
* <p/>
27+
* The annotation {@link #value()} is mandatory and define the URI or the full
28+
* URL of the web service. It MAY contain placeholders defined as follow :
29+
* <code>{name}</code>
30+
* <p/>
31+
* The annotated method MAY have parameters as soon as each parameter names are
32+
* present as placeholders in the URI.
33+
* <p/>
34+
* The annotated method CAN return <code>void</code>,
35+
* {@link org.springframework.http.ResponseEntity} or any concrete java classes.
36+
* Interfaces CAN'T be used as return type because converters have to know which
37+
* object to instantiate while returning result.
38+
* <p/>
39+
* <b>Note:</b> Generics classes are also supported both for return type and
40+
* parameters.
41+
* <p/>
42+
* <blockquote>
43+
*
44+
* <b>Example :</b>
45+
*
46+
* <pre>
47+
* &#064;Rest(rootUrl = &quot;http://myserver&quot;, converters = MappingJacksonHttpMessageConverter.class)
48+
* public interface MyRestClient {
49+
*
50+
* &#064;Get(&quot;/events&quot;)
51+
* EventList getEvents();
52+
*
53+
* &#064;Get(&quot;/events/<b>{max}</b>&quot;)
54+
* ResponseEntity&lt;EventList> getEvents(int <b>max</b>);
55+
*
56+
* &#064;Get(&quot;/events/<b>{max}</b>/<b>{filter}</b>&quot;)
57+
* ArrayList&lt;Event> getEvents(int <b>max</b>, String <b>filter</b>);
58+
* }
59+
* </pre>
60+
*
61+
* </blockquote>
62+
*
63+
* @see Rest
64+
* @see Post
65+
* @see Put
66+
* @see Delete
67+
* @see Head
68+
* @see Options
69+
*/
2370
@Retention(RetentionPolicy.CLASS)
2471
@Target(ElementType.METHOD)
2572
public @interface Get {

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/rest/Head.java‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,38 @@
2020
import java.lang.annotation.RetentionPolicy;
2121
import java.lang.annotation.Target;
2222

23+
/**
24+
* Use on methods in {@link Rest} annotated class to add a new rest service of
25+
* type OPTIONS.
26+
* <p/>
27+
* This annotation as the same constraints as {@link Get} but it MUST return
28+
* {@link org.springframework.http.HttpHeaders}
29+
* <p/>
30+
* <blockquote>
31+
*
32+
* <b>Example :</b>
33+
*
34+
* <pre>
35+
* &#064;Rest(rootUrl = &quot;http://myserver&quot;, converters = MappingJacksonHttpMessageConverter.class)
36+
* public interface MyRestClient {
37+
*
38+
* &#064;Head(&quot;/events&quot;)
39+
* HttpHeaders getEventHeader();
40+
*
41+
* &#064;Head(&quot;/events/{year}/{location}&quot;)
42+
* HttpHeaders getEventHeader2(String location, int year);
43+
* }
44+
* </pre>
45+
*
46+
* </blockquote>
47+
*
48+
* @see Rest
49+
* @see Get
50+
* @see Post
51+
* @see Put
52+
* @see Delete
53+
* @see Options
54+
*/
2355
@Retention(RetentionPolicy.CLASS)
2456
@Target(ElementType.METHOD)
2557
public @interface Head {

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/rest/Options.java‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -19,7 +19,40 @@
1919
import java.lang.annotation.Retention;
2020
import java.lang.annotation.RetentionPolicy;
2121
import java.lang.annotation.Target;
22+
import java.util.Set;
2223

24+
/**
25+
* Use on methods in {@link Rest} annotated class to add a new rest service of
26+
* type OPTIONS.
27+
* <p/>
28+
* This annotation as the same constraints as {@link Get} but it MUST return a
29+
* {@link Set} of {@link org.springframework.http.HttpMethod}
30+
* <p/>
31+
* <blockquote>
32+
*
33+
* <b>Example :</b>
34+
*
35+
* <pre>
36+
* &#064;Rest(rootUrl = &quot;http://myserver&quot;, converters = MappingJacksonHttpMessageConverter.class)
37+
* public interface MyRestClient {
38+
*
39+
* &#064;Options(&quot;/events&quot;)
40+
* Set&lt;HttpMethod&gt; getEventOptions();
41+
*
42+
* &#064;Options(&quot;/events/{year}/{location}&quot;)
43+
* Set&lt;HttpMethod&gt; getEventOptions(String location, int year);
44+
* }
45+
* </pre>
46+
*
47+
* </blockquote>
48+
*
49+
* @see Rest
50+
* @see Get
51+
* @see Post
52+
* @see Put
53+
* @see Delete
54+
* @see Head
55+
*/
2356
@Retention(RetentionPolicy.CLASS)
2457
@Target(ElementType.METHOD)
2558
public @interface Options {

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/rest/Post.java‎

Lines changed: 34 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,40 @@
2020
import java.lang.annotation.RetentionPolicy;
2121
import java.lang.annotation.Target;
2222

23+
/**
24+
* Use on methods in {@link Rest} annotated class to add a new rest service of
25+
* type POST.
26+
* <p/>
27+
* This annotation as the same constraints as {@link Get}.
28+
* <p/>
29+
* If an extra parameter is present (ie the only one not mapped with URI
30+
* placeholders) it will be send in the request body using given converter.
31+
* <p/>
32+
* <blockquote>
33+
*
34+
* <b>Example :</b>
35+
*
36+
* <pre>
37+
* &#064;Rest(rootUrl = &quot;http://myserver&quot;, converters = MappingJacksonHttpMessageConverter.class)
38+
* public interface MyRestClient {
39+
*
40+
* &#064;Post(&quot;/events/new/random&quot;)
41+
* Event newEvent();
42+
*
43+
* &#064;Post(&quot;/events/new/<b>{id}</b>&quot;)
44+
* void newEvent(Event <i>event</i>, int <b>id</b>);
45+
* }
46+
* </pre>
47+
*
48+
* </blockquote>
49+
*
50+
* @see Rest
51+
* @see Get
52+
* @see Put
53+
* @see Delete
54+
* @see Head
55+
* @see Options
56+
*/
2357
@Retention(RetentionPolicy.CLASS)
2458
@Target(ElementType.METHOD)
2559
public @interface Post {

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/rest/Put.java‎

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -20,6 +20,37 @@
2020
import java.lang.annotation.RetentionPolicy;
2121
import java.lang.annotation.Target;
2222

23+
/**
24+
* Use on methods in {@link Rest} annotated class to add a new rest service of
25+
* type PUT.
26+
* <p/>
27+
* This annotation as the EXACT same constraints as {@link Post}.
28+
* <p/>
29+
* <blockquote>
30+
*
31+
* <b>Example :</b>
32+
*
33+
* <pre>
34+
* &#064;Rest(rootUrl = &quot;http://myserver&quot;, converters = MappingJacksonHttpMessageConverter.class)
35+
* public interface MyRestClient {
36+
*
37+
* &#064;Put(&quot;/events/update/last&quot;)
38+
* Event updateEvent();
39+
*
40+
* &#064;Put(&quot;/events/update/<b>{id}</b>&quot;)
41+
* void updateEvent(Event <i>event</i>, int <b>id</b>);
42+
* }
43+
* </pre>
44+
*
45+
* </blockquote>
46+
*
47+
* @see Rest
48+
* @see Get
49+
* @see Post
50+
* @see Delete
51+
* @see Head
52+
* @see Options
53+
*/
2354
@Retention(RetentionPolicy.CLASS)
2455
@Target(ElementType.METHOD)
2556
public @interface Put {

‎AndroidAnnotations/androidannotations-api/src/main/java/org/androidannotations/annotations/rest/RequiresAuthentication.java‎

Lines changed: 51 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,58 @@
2020
import java.lang.annotation.RetentionPolicy;
2121
import java.lang.annotation.Target;
2222

23+
/**
24+
* Use on {@link Get}, {@link Post}, … annotated methods to use authentication
25+
* on the request.
26+
* <p/>
27+
* To set the current authentication object to use, yout MUST add the following
28+
* method to your interface :
29+
* <code>void setAuthentication(org.springframework.http.HttpAuthentication auth)</code>.
30+
* <p/>
31+
* You can also add this specific method for <a
32+
* href="https://en.wikipedia.org/wiki/Basic_access_authentication">Basic
33+
* Authentication</a> :
34+
* <code>setHttpBasicAuth(String username, String password)</code>.
35+
* <p/>
36+
* <blockquote>
37+
*
38+
* <b>Example :</b>
39+
*
40+
* <pre>
41+
* &#064;Rest(rootUrl = &quot;http://myserver&quot;, converters = MappingJacksonHttpMessageConverter.class)
42+
* public interface MyRestClient {
43+
*
44+
* &#064;Get("/events/{id}")
45+
* &#064;RequiresAuthentication
46+
* Event getEvent(long id);
47+
*
48+
* setHttpBasicAuth(String username, String password);
49+
* }
50+
*
51+
* &#064;EBean
52+
* public class MyBean {
53+
*
54+
* &#064;RestService MyRestClient;
55+
*
56+
* &#064;AfterInject
57+
* public void init() {
58+
* myRestClient.setHttpBasicAuth("user", "password");
59+
* }
60+
* }
61+
* </pre>
62+
*
63+
* </blockquote>
64+
*
65+
* @see Rest
66+
* @see Get
67+
* @see Post
68+
* @see Put
69+
* @see Delete
70+
* @see Head
71+
* @see Options
72+
*/
2373
@Retention(RetentionPolicy.CLASS)
2474
@Target({ ElementType.METHOD, ElementType.TYPE })
2575
public @interface RequiresAuthentication {
26-
76+
2777
}

0 commit comments

Comments
 (0)