Threading.java
001 /*
002  * SPDX-License-Identifier: Apache-2.0
003  *
004  * Copyright 2008-2017 the original author or authors.
005  *
006  * Licensed under the Apache License, Version 2.0 (the "License");
007  * you may not use this file except in compliance with the License.
008  * You may obtain a copy of the License at
009  *
010  *     http://www.apache.org/licenses/LICENSE-2.0
011  *
012  * Unless required by applicable law or agreed to in writing, software
013  * distributed under the License is distributed on an "AS IS" BASIS,
014  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
015  * See the License for the specific language governing permissions and
016  * limitations under the License.
017  */
018 package griffon.transform;
019 
020 import java.lang.annotation.ElementType;
021 import java.lang.annotation.Retention;
022 import java.lang.annotation.RetentionPolicy;
023 import java.lang.annotation.Target;
024 
025 /**
026  <p>Annotates a calls or method.</p>
027  <p/>
028  * Annotated elements must follow these rules
029  <ul>
030  <li>must be a public method</li>
031  <li>name does not match an event handler</li>
032  <li>must pass {@code griffon.util.GriffonClassUtils.isPlainMethod()} if it's a method</li>
033  </ul>
034  <p/>
035  * This annotation takes {@code griffon.util.Threading.Policy} as value, with {@code Threading.Policy.OUTSIDE_UITHREAD} being
036  * the default value.<p>
037  <p/>
038  <p>The following snippet exemplifies the compactness of code when the annotation is applied </p>
039  <pre>
040  * import griffon.transform.Threading
041  *
042  * class Sample {
043  *     &#064;Threading
044  *     void doSomethingOutside(String arg) {
045  *         println "Outside $arg"
046  *     }
047  *     &#064;Threading(Threading.Policy.INSIDE_UITHREAD_SYNC)
048  *     void doSomethingInside(String arg) {
049  *         println "Inside $arg"
050  *     }
051  * }
052  </pre>
053  <p/>
054  <p>The equivalent, non-annotated code is</p>
055  <pre>
056  * import griffon.core.threading.UIThreadManager
057  *
058  * class Sample {
059  *     void doSomethingOutside(String arg) {
060  *         UIThreadManager.instance.runOutsideUI {
061  *             println "Outside $arg"
062  *         }
063  *     }
064  *     void doSomethingInside(String arg) {
065  *         UIThreadManager.instance.runInsideUISync {
066  *             println "Inside $arg"
067  *         }
068  *     }
069  * }
070  </pre>
071  *
072  @author Andres Almiray
073  @see Threading.Policy
074  @since 2.0.0
075  */
076 @Retention(RetentionPolicy.RUNTIME)
077 @Target({ElementType.TYPE, ElementType.METHOD})
078 public @interface Threading {
079     Policy value() default Policy.OUTSIDE_UITHREAD;
080 
081     /**
082      * Indicates the type of threading management for a method or property.</p>
083      * The following values apply
084      <ul>
085      <li>{@code SKIP} - no threading management will be performed.</li>
086      <li>{@code OUTSIDE_UITHREAD} - code should be invoked outside of the UI thread.</li>
087      <li>{@code OUTSIDE_UITHREAD_ASYNC} - code should be invoked on a background thread, always.</li>
088      <li>{@code INSIDE_UITHREAD_SYNC} - code should be invoked inside the UI thread using a synchronous call.</li>
089      <li>{@code INSIDE_UITHREAD_ASYNC} - code should be invoked inside the UI thread using an asynchronous call.</li>
090      </ul>
091      *
092      @author Andres Almiray
093      @see Threading
094      @since 2.0.0
095      */
096     public enum Policy {
097         /**
098          * Skip threading injection
099          */
100         SKIP,
101         /**
102          * Inject runOutsideUI wrapper
103          */
104         OUTSIDE_UITHREAD,
105         /**
106          * Inject runOutsideUIAsync wrapper
107          */
108         OUTSIDE_UITHREAD_ASYNC,
109         /**
110          * Inject runInsideUISync wrapper
111          */
112         INSIDE_UITHREAD_SYNC,
113         /**
114          * Inject runInsideUIAsync wrapper
115          */
116         INSIDE_UITHREAD_ASYNC
117     }
118 }