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 #ifndef TENSORFLOW_JAVA_SRC_GEN_CC_JAVA_DEFS_H_ 17 #define TENSORFLOW_JAVA_SRC_GEN_CC_JAVA_DEFS_H_ 18 19 #include <list> 20 #include <map> 21 #include <string> 22 #include <utility> 23 24 #include "tensorflow/core/framework/types.h" 25 26 namespace tensorflow { 27 namespace java { 28 29 // An enumeration of different modifiers commonly used in Java 30 enum Modifier { 31 PACKAGE = 0, 32 PUBLIC = (1 << 0), 33 PROTECTED = (1 << 1), 34 PRIVATE = (1 << 2), 35 STATIC = (1 << 3), 36 FINAL = (1 << 4), 37 }; 38 39 class Annotation; 40 41 // A definition of any kind of Java type (classes, interfaces...) 42 // 43 // Note that most of the data fields of this class are only useful in specific 44 // contexts and are not required in many cases. For example, annotations and 45 // supertypes are only useful when declaring a type. 46 class Type { 47 public: 48 enum Kind { 49 PRIMITIVE, CLASS, INTERFACE, ENUM, GENERIC, ANNOTATION 50 }; Byte()51 static const Type Byte() { 52 return Type(Type::PRIMITIVE, "byte"); 53 } Char()54 static const Type Char() { 55 return Type(Type::PRIMITIVE, "char"); 56 } Short()57 static const Type Short() { 58 return Type(Type::PRIMITIVE, "short"); 59 } Int()60 static const Type Int() { 61 return Type(Type::PRIMITIVE, "int"); 62 } Long()63 static const Type Long() { 64 return Type(Type::PRIMITIVE, "long"); 65 } Float()66 static const Type Float() { 67 return Type(Type::PRIMITIVE, "float"); 68 } Double()69 static const Type Double() { 70 return Type(Type::PRIMITIVE, "double"); 71 } Boolean()72 static const Type Boolean() { 73 return Type(Type::PRIMITIVE, "boolean"); 74 } Void()75 static const Type Void() { 76 // For simplicity, we consider 'void' as a primitive type, like the Java 77 // Reflection API does 78 return Type(Type::PRIMITIVE, "void"); 79 } Generic(const string & name)80 static Type Generic(const string& name) { return Type(Type::GENERIC, name); } Wildcard()81 static Type Wildcard() { return Type(Type::GENERIC, ""); } 82 static Type Class(const string& name, const string& package = "") { 83 return Type(Type::CLASS, name, package); 84 } 85 static Type Interface(const string& name, const string& package = "") { 86 return Type(Type::INTERFACE, name, package); 87 } 88 static Type Enum(const string& name, const string& package = "") { 89 return Type(Type::ENUM, name, package); 90 } ClassOf(const Type & type)91 static Type ClassOf(const Type& type) { 92 return Class("Class").add_parameter(type); 93 } ListOf(const Type & type)94 static Type ListOf(const Type& type) { 95 return Interface("List", "java.util").add_parameter(type); 96 } IterableOf(const Type & type)97 static Type IterableOf(const Type& type) { 98 return Interface("Iterable").add_parameter(type); 99 } ForDataType(DataType data_type)100 static Type ForDataType(DataType data_type) { 101 switch (data_type) { 102 case DataType::DT_BOOL: 103 return Class("Boolean"); 104 case DataType::DT_STRING: 105 return Class("String"); 106 case DataType::DT_FLOAT: 107 return Class("Float"); 108 case DataType::DT_DOUBLE: 109 return Class("Double"); 110 case DataType::DT_UINT8: 111 return Class("UInt8", "org.tensorflow.types"); 112 case DataType::DT_INT32: 113 return Class("Integer"); 114 case DataType::DT_INT64: 115 return Class("Long"); 116 case DataType::DT_RESOURCE: 117 // TODO(karllessard) create a Resource utility class that could be 118 // used to store a resource and its type (passed in a second argument). 119 // For now, we need to force a wildcard and we will unfortunately lose 120 // track of the resource type. 121 // Falling through... 122 default: 123 // Any other datatypes does not have a equivalent in Java and must 124 // remain a wildcard (e.g. DT_COMPLEX64, DT_QINT8, ...) 125 return Wildcard(); 126 } 127 } kind()128 const Kind& kind() const { return kind_; } name()129 const string& name() const { return name_; } package()130 const string& package() const { return package_; } canonical_name()131 const string canonical_name() const { 132 return package_.empty() ? name_ : package_ + "." + name_; 133 } wildcard()134 bool wildcard() const { return name_.empty(); } // only wildcards has no name parameters()135 const std::list<Type>& parameters() const { return parameters_; } add_parameter(const Type & parameter)136 Type& add_parameter(const Type& parameter) { 137 parameters_.push_back(parameter); 138 return *this; 139 } annotations()140 const std::list<Annotation>& annotations() const { return annotations_; } add_annotation(const Annotation & annotation)141 Type& add_annotation(const Annotation& annotation) { 142 annotations_.push_back(annotation); 143 return *this; 144 } supertypes()145 const std::list<Type>& supertypes() const { return supertypes_; } add_supertype(const Type & type)146 Type& add_supertype(const Type& type) { 147 if (type.kind_ == CLASS) { 148 supertypes_.push_front(type); // keep superclass at the front of the list 149 } else if (type.kind_ == INTERFACE) { 150 supertypes_.push_back(type); 151 } 152 return *this; 153 } 154 155 protected: 156 Type(Kind kind, const string& name, const string& package = "") kind_(kind)157 : kind_(kind), name_(name), package_(package) {} 158 159 private: 160 Kind kind_; 161 string name_; 162 string package_; 163 std::list<Type> parameters_; 164 std::list<Annotation> annotations_; 165 std::list<Type> supertypes_; 166 }; 167 168 // Definition of a Java annotation 169 // 170 // This class only defines the usage of an annotation in a specific context, 171 // giving optionally a set of attributes to initialize. 172 class Annotation : public Type { 173 public: 174 static Annotation Create(const string& type_name, const string& pkg = "") { 175 return Annotation(type_name, pkg); 176 } attributes()177 const string& attributes() const { return attributes_; } attributes(const string & attributes)178 Annotation& attributes(const string& attributes) { 179 attributes_ = attributes; 180 return *this; 181 } 182 183 private: 184 string attributes_; 185 Annotation(const string & name,const string & package)186 Annotation(const string& name, const string& package) 187 : Type(Kind::ANNOTATION, name, package) {} 188 }; 189 190 // A definition of a Java variable 191 // 192 // This class declares an instance of a type, such as a class field or a 193 // method argument, which can be documented. 194 class Variable { 195 public: Create(const string & name,const Type & type)196 static Variable Create(const string& name, const Type& type) { 197 return Variable(name, type, false); 198 } Varargs(const string & name,const Type & type)199 static Variable Varargs(const string& name, const Type& type) { 200 return Variable(name, type, true); 201 } name()202 const string& name() const { return name_; } type()203 const Type& type() const { return type_; } variadic()204 bool variadic() const { return variadic_; } 205 206 private: 207 string name_; 208 Type type_; 209 bool variadic_; 210 Variable(const string & name,const Type & type,bool variadic)211 Variable(const string& name, const Type& type, bool variadic) 212 : name_(name), type_(type), variadic_(variadic) {} 213 }; 214 215 // A definition of a Java class method 216 // 217 // This class defines the signature of a method, including its name, return 218 // type and arguments. 219 class Method { 220 public: Create(const string & name,const Type & return_type)221 static Method Create(const string& name, const Type& return_type) { 222 return Method(name, return_type, false); 223 } ConstructorFor(const Type & clazz)224 static Method ConstructorFor(const Type& clazz) { 225 return Method(clazz.name(), clazz, true); 226 } constructor()227 bool constructor() const { return constructor_; } name()228 const string& name() const { return name_; } return_type()229 const Type& return_type() const { return return_type_; } arguments()230 const std::list<Variable>& arguments() const { return arguments_; } add_argument(const Variable & var)231 Method& add_argument(const Variable& var) { 232 arguments_.push_back(var); 233 return *this; 234 } annotations()235 const std::list<Annotation>& annotations() const { return annotations_; } add_annotation(const Annotation & annotation)236 Method& add_annotation(const Annotation& annotation) { 237 annotations_.push_back(annotation); 238 return *this; 239 } 240 241 private: 242 string name_; 243 Type return_type_; 244 bool constructor_; 245 std::list<Variable> arguments_; 246 std::list<Annotation> annotations_; 247 Method(const string & name,const Type & return_type,bool constructor)248 Method(const string& name, const Type& return_type, bool constructor) 249 : name_(name), return_type_(return_type), constructor_(constructor) {} 250 }; 251 252 // A definition of a documentation bloc for a Java element (JavaDoc) 253 class Javadoc { 254 public: 255 static Javadoc Create(const string& brief = "") { return Javadoc(brief); } brief()256 const string& brief() const { return brief_; } details()257 const string& details() const { return details_; } details(const string & details)258 Javadoc& details(const string& details) { 259 details_ = details; 260 return *this; 261 } tags()262 const std::list<std::pair<string, string>>& tags() const { return tags_; } add_tag(const string & tag,const string & text)263 Javadoc& add_tag(const string& tag, const string& text) { 264 tags_.push_back(std::make_pair(tag, text)); 265 return *this; 266 } add_param_tag(const string & name,const string & text)267 Javadoc& add_param_tag(const string& name, const string& text) { 268 return add_tag("param", name + " " + text); 269 } 270 271 private: 272 string brief_; 273 string details_; 274 std::list<std::pair<string, string>> tags_; 275 Javadoc(const string & brief)276 explicit Javadoc(const string& brief) : brief_(brief) {} 277 }; 278 279 } // namespace java 280 } // namespace tensorflow 281 282 #endif // TENSORFLOW_JAVA_SRC_GEN_CC_JAVA_DEFS_H_ 283