1 /* Copyright 2017 The TensorFlow Authors. All Rights Reserved. 2 3 Licensed under the Apache License, Version 2.0 (the "License"); 4 you may not use this file except in compliance with the License. 5 You may obtain a copy of the License at 6 7 http://www.apache.org/licenses/LICENSE-2.0 8 9 Unless required by applicable law or agreed to in writing, software 10 distributed under the License is distributed on an "AS IS" BASIS, 11 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 See the License for the specific language governing permissions and 13 limitations under the License. 14 ==============================================================================*/ 15 16 package org.tensorflow.op.annotation; 17 18 import java.lang.annotation.Documented; 19 import java.lang.annotation.ElementType; 20 import java.lang.annotation.Retention; 21 import java.lang.annotation.RetentionPolicy; 22 import java.lang.annotation.Target; 23 24 /** 25 * Annotation used by classes to make TensorFlow operations conveniently accessible via {@code 26 * org.tensorflow.op.Ops}. 27 * 28 * <p>An annotation processor ({@code org.tensorflow.processor.OperatorProcessor}) builds the 29 * {@code Ops} class by aggregating all classes annotated as {@code @Operator}s. Each annotated 30 * class <b>must</b> have at least one public static factory method named {@code create} that 31 * accepts a {@link org.tensorflow.op.Scope} as its first argument. The processor then adds a 32 * convenience method in the {@code Ops} class. For example: 33 * 34 * <pre>{@code 35 * @Operator 36 * public final class MyOp implements Op { 37 * public static MyOp create(Scope scope, Operand operand) { 38 * ... 39 * } 40 * } 41 * }</pre> 42 * 43 * <p>results in a method in the {@code Ops} class 44 * 45 * <pre>{@code 46 * import org.tensorflow.op.Ops; 47 * ... 48 * Ops ops = Ops.create(graph); 49 * ... 50 * ops.myOp(operand); 51 * // and has exactly the same effect as calling 52 * // MyOp.create(ops.getScope(), operand); 53 * }</pre> 54 */ 55 @Documented 56 @Target(ElementType.TYPE) 57 @Retention(RetentionPolicy.SOURCE) 58 public @interface Operator { 59 /** 60 * Specify an optional group within the {@code Ops} class. 61 * 62 * <p>By default, an annotation processor will create convenience methods directly in the {@code 63 * Ops} class. An annotated operator may optionally choose to place the method within a group. For 64 * example: 65 * 66 * <pre>{@code 67 * @Operator(group="math") 68 * public final class Add extends PrimitiveOp implements Operand { 69 * ... 70 * } 71 * }</pre> 72 * 73 * <p>results in the {@code add} method placed within a {@code math} group within the {@code Ops} 74 * class. 75 * 76 * <pre>{@code 77 * ops.math().add(...); 78 * }</pre> 79 * 80 * <p>The group name must be a <a 81 * href="https://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.8">valid Java 82 * identifier</a>. 83 */ group()84 String group() default ""; 85 86 /** 87 * Name for the wrapper method used in the {@code Ops} class. 88 * 89 * <p>By default, a processor derives the method name in the {@code Ops} class from the class name 90 * of the operator. This attribute allow you to provide a different name instead. For example: 91 * 92 * <pre>{@code 93 * @Operator(name="myOperation") 94 * public final class MyRealOperation implements Operand { 95 * public static MyRealOperation create(...) 96 * } 97 * }</pre> 98 * 99 * <p>results in this method added to the {@code Ops} class 100 * 101 * <pre>{@code 102 * ops.myOperation(...); 103 * // and is the same as calling 104 * // MyRealOperation.create(...) 105 * }</pre> 106 * 107 * <p>The name must be a <a 108 * href="https://docs.oracle.com/javase/specs/jls/se7/html/jls-3.html#jls-3.8">valid Java 109 * identifier</a>. 110 */ name()111 String name() default ""; 112 } 113