1    /*
2     * Copyright 2008 :torweg free software group
3     * 
4     * This program is free software: you can redistribute it and/or modify
5     * it under the terms of the GNU General Public License as published by
6     * the Free Software Foundation, either version 3 of the License, or
7     * (at your option) any later version.
8     * 
9     * This program is distributed in the hope that it will be useful,
10    * but WITHOUT ANY WARRANTY; without even the implied warranty of
11    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
12    * GNU General Public License for more details.
13    * 
14    * You should have received a copy of the GNU General Public License
15    * along with this program.  If not, see <http://www.gnu.org/licenses/>.
16    *
17    */
18   package org.torweg.pulse.annotations;
19   
20   import java.lang.annotation.Documented;
21   import java.lang.annotation.ElementType;
22   import java.lang.annotation.Retention;
23   import java.lang.annotation.RetentionPolicy;
24   import java.lang.annotation.Target;
25   
26   /**
27    * defines the action (see
28    * {@link org.torweg.pulse.service.request.Command#getAction()}) which triggers
29    * the annotated method of a {@link org.torweg.pulse.bundle.Controller}.
30    * <p>
31    * Methods annotated with {@code @Action} can have a return type of either
32    * {@code null}, {@code Result} or any JAXB enabled {@code Object}. Allowed
33    * method Parameters are {@code Bundle}, {@code ServiceRequest} and any class
34    * annotated with {@code @RequestBean} or nay combination thereof.
35    * </p>
36    * 
37    * @see org.torweg.pulse.bundle.Controller
38    * @see org.torweg.pulse.service.request.Command
39    * @author Thomas Weber
40    * @version $Revision: 1954 $
41    */
42   @Documented
43   @Retention(RetentionPolicy.RUNTIME)
44   @Target({ ElementType.METHOD })
45   public @interface Action {
46   
47       /**
48        * the name of the action.
49        * 
50        * @see org.torweg.pulse.service.request.Command#getAction()
51        */
52       String value();
53   
54       /**
55        * shall the {@code CommandGenerator} include this {@code Action} as a
56        * generated {@code Command}; default {@code false}.
57        */
58       boolean generate() default false;
59   
60       /**
61        * shall the generated {@code Command} use a secure connection (if
62        * available); default {@link Security#KEEP}.
63        */
64       Security security() default Security.KEEP;
65   
66       /**
67        * shall the sitemap ID be stripped from the generated {@code Command}, if
68        * {@link Action#generate()} is {@code true}; default {@code true}.
69        */
70       boolean stripSitemapID() default true;
71   
72       /**
73        * shall the suffix be stripped from the generated {@code Command}, if
74        * {@link Action#generate()} is {@code true}; default {@code false}.
75        */
76       boolean stripSuffix() default false;
77   
78       /**
79        * shall multipart/form-data based uploads be allowed for the {@code Action}
80        * ; default {@code false}.
81        */
82       boolean uploadAllowed() default false;
83   
84       /* ------------------- SECURITY ENUM ---------------- */
85   
86       /**
87        * indicates which level of security shall be applied to the generated
88        * action.
89        */
90       public enum Security {
91   
92           /**
93            * never use a secure connection.
94            */
95           NEVER(0),
96   
97           /**
98            * keep the current security level, i.e. stay on https, if the preceding
99            * command was secure, stay on http if the preceding command was not
100           * secure.
101           */
102          KEEP(100),
103  
104          /**
105           * always use a secure connection, if TLS is available.
106           */
107          ALWAYS(1000);
108  
109          /**
110           * an int value used in comparisons.
111           */
112          private int value;
113  
114          /**
115           * internal constructor.
116           * 
117           * @param v
118           *            the int value
119           */
120          private Security(final int v) {
121              this.value = v;
122          }
123  
124          /**
125           * returns whether the current level of {@code Security} overrides the
126           * given {@code Security}.
127           * 
128           * @param s
129           *            the security to check against
130           * @return whether the current level of {@code Security} overrides the
131           *         given {@code Security}
132           */
133          public final boolean overrides(final Security s) {
134              return (this.value > s.value);
135          }
136      }
137  }
138