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 * @Threading
044 * void doSomethingOutside(String arg) {
045 * println "Outside $arg"
046 * }
047 * @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 }
|