/* * Copyright (C) 2015 The Android Open Source Project * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ #include "java/JavaClassGenerator.h" #include #include #include #include #include #include "android-base/errors.h" #include "android-base/logging.h" #include "android-base/stringprintf.h" #include "androidfw/StringPiece.h" #include "NameMangler.h" #include "Resource.h" #include "ResourceTable.h" #include "ResourceValues.h" #include "SdkConstants.h" #include "ValueVisitor.h" #include "java/AnnotationProcessor.h" #include "java/ClassDefinition.h" #include "process/SymbolTable.h" using ::aapt::io::OutputStream; using ::aapt::text::Printer; using ::android::StringPiece; using ::android::base::StringPrintf; namespace aapt { static const std::set sJavaIdentifiers = { "abstract", "assert", "boolean", "break", "byte", "case", "catch", "char", "class", "const", "continue", "default", "do", "double", "else", "enum", "extends", "final", "finally", "float", "for", "goto", "if", "implements", "import", "instanceof", "int", "interface", "long", "native", "new", "package", "private", "protected", "public", "return", "short", "static", "strictfp", "super", "switch", "synchronized", "this", "throw", "throws", "transient", "try", "void", "volatile", "while", "true", "false", "null"}; static bool IsValidSymbol(const StringPiece& symbol) { return sJavaIdentifiers.find(symbol) == sJavaIdentifiers.end(); } // Java symbols can not contain . or -, but those are valid in a resource name. // Replace those with '_'. std::string JavaClassGenerator::TransformToFieldName(const StringPiece& symbol) { std::string output = symbol.to_string(); for (char& c : output) { if (c == '.' || c == '-') { c = '_'; } } return output; } // Transforms an attribute in a styleable to the Java field name: // // // // // // // Foo_android_bar // Foo_bar static std::string TransformNestedAttr(const ResourceNameRef& attr_name, const std::string& styleable_class_name, const StringPiece& package_name_to_generate) { std::string output = styleable_class_name; // We may reference IDs from other packages, so prefix the entry name with // the package. if (!attr_name.package.empty() && package_name_to_generate != attr_name.package) { output += "_" + JavaClassGenerator::TransformToFieldName(attr_name.package); } output += "_" + JavaClassGenerator::TransformToFieldName(attr_name.entry); return output; } static void AddAttributeFormatDoc(AnnotationProcessor* processor, Attribute* attr) { const uint32_t type_mask = attr->type_mask; if (type_mask & android::ResTable_map::TYPE_REFERENCE) { processor->AppendComment( "

May be a reference to another resource, in the form\n" "\"@[+][package:]type/name\" or a " "theme\n" "attribute in the form\n" "\"?[package:]type/name\"."); } if (type_mask & android::ResTable_map::TYPE_STRING) { processor->AppendComment( "

May be a string value, using '\\\\;' to escape characters such as\n" "'\\\\n' or '\\\\uxxxx' for a unicode character;"); } if (type_mask & android::ResTable_map::TYPE_INTEGER) { processor->AppendComment( "

May be an integer value, such as \"100\"."); } if (type_mask & android::ResTable_map::TYPE_BOOLEAN) { processor->AppendComment( "

May be a boolean value, such as \"true\" or\n" "\"false\"."); } if (type_mask & android::ResTable_map::TYPE_COLOR) { processor->AppendComment( "

May be a color value, in the form of " "\"#rgb\",\n" "\"#argb\", \"#rrggbb\", or \n" "\"#aarrggbb\"."); } if (type_mask & android::ResTable_map::TYPE_FLOAT) { processor->AppendComment( "

May be a floating point value, such as \"1.2\"."); } if (type_mask & android::ResTable_map::TYPE_DIMENSION) { processor->AppendComment( "

May be a dimension value, which is a floating point number " "appended with a\n" "unit such as \"14.5sp\".\n" "Available units are: px (pixels), dp (density-independent pixels),\n" "sp (scaled pixels based on preferred font size), in (inches), and\n" "mm (millimeters)."); } if (type_mask & android::ResTable_map::TYPE_FRACTION) { processor->AppendComment( "

May be a fractional value, which is a floating point number " "appended with\n" "either % or %p, such as \"14.5%\".\n" "The % suffix always means a percentage of the base size;\n" "the optional %p suffix provides a size relative to some parent " "container."); } if (type_mask & (android::ResTable_map::TYPE_FLAGS | android::ResTable_map::TYPE_ENUM)) { if (type_mask & android::ResTable_map::TYPE_FLAGS) { processor->AppendComment( "

Must be one or more (separated by '|') of the following " "constant values.

"); } else { processor->AppendComment( "

Must be one of the following constant values.

"); } processor->AppendComment( "\n\n" "\n" "\n" "\n"); for (const Attribute::Symbol& symbol : attr->symbols) { std::stringstream line; line << "" << "" << ""; processor->AppendComment(line.str()); } processor->AppendComment("
ConstantValueDescription
" << symbol.symbol.name.value().entry << "" << std::hex << symbol.value << std::dec << "" << util::TrimWhitespace(symbol.symbol.GetComment()) << "
"); } } JavaClassGenerator::JavaClassGenerator(IAaptContext* context, ResourceTable* table, const JavaClassGeneratorOptions& options) : context_(context), table_(table), options_(options) {} bool JavaClassGenerator::SkipSymbol(Visibility::Level level) { switch (options_.types) { case JavaClassGeneratorOptions::SymbolTypes::kAll: return false; case JavaClassGeneratorOptions::SymbolTypes::kPublicPrivate: return level == Visibility::Level::kUndefined; case JavaClassGeneratorOptions::SymbolTypes::kPublic: return level != Visibility::Level::kPublic; } return true; } // Whether or not to skip writing this symbol. bool JavaClassGenerator::SkipSymbol(const Maybe& symbol) { return !symbol || (options_.types == JavaClassGeneratorOptions::SymbolTypes::kPublic && !symbol.value().is_public); } struct StyleableAttr { const Reference* attr_ref = nullptr; std::string field_name; Maybe symbol; }; static bool operator<(const StyleableAttr& lhs, const StyleableAttr& rhs) { const ResourceId lhs_id = lhs.attr_ref->id.value_or_default(ResourceId(0)); const ResourceId rhs_id = rhs.attr_ref->id.value_or_default(ResourceId(0)); if (lhs_id == rhs_id) { return lhs.attr_ref->name.value() < rhs.attr_ref->name.value(); } return cmp_ids_dynamic_after_framework(lhs_id, rhs_id); } static FieldReference GetRFieldReference(const ResourceName& name, StringPiece fallback_package_name) { const std::string package_name = name.package.empty() ? fallback_package_name.to_string() : name.package; const std::string entry = JavaClassGenerator::TransformToFieldName(name.entry); return FieldReference( StringPrintf("%s.R.%s.%s", package_name.c_str(), to_string(name.type).data(), entry.c_str())); } bool JavaClassGenerator::ProcessStyleable(const ResourceNameRef& name, const ResourceId& id, const Styleable& styleable, const StringPiece& package_name_to_generate, ClassDefinition* out_class_def, MethodDefinition* out_rewrite_method, Printer* r_txt_printer) { const std::string array_field_name = TransformToFieldName(name.entry); std::unique_ptr array_def = util::make_unique(array_field_name); // The array must be sorted by resource ID. std::vector sorted_attributes; sorted_attributes.reserve(styleable.entries.size()); for (const auto& attr : styleable.entries) { // If we are not encoding final attributes, the styleable entry may have no // ID if we are building a static library. CHECK(!options_.use_final || attr.id) << "no ID set for Styleable entry"; CHECK(bool(attr.name)) << "no name set for Styleable entry"; // We will need the unmangled, transformed name in the comments and the field, // so create it once and cache it in this StyleableAttr data structure. StyleableAttr styleable_attr; styleable_attr.attr_ref = &attr; // The field name for this attribute is prefixed by the name of this styleable and // the package it comes from. styleable_attr.field_name = TransformNestedAttr(attr.name.value(), array_field_name, package_name_to_generate); Reference ref = attr; if (attr.name.value().package.empty()) { // If the resource does not have a package name, set the package to the unmangled package name // of the styleable declaration because attributes without package names would have been // declared in the same package as the styleable. ref.name = ResourceName(package_name_to_generate, ref.name.value().type, ref.name.value().entry); } // Look up the symbol so that we can write out in the comments what are possible legal values // for this attribute. const SymbolTable::Symbol* symbol = context_->GetExternalSymbols()->FindByReference(ref); if (symbol && symbol->attribute) { // Copy the symbol data structure because the returned instance can be destroyed. styleable_attr.symbol = *symbol; } sorted_attributes.push_back(std::move(styleable_attr)); } // Sort the attributes by ID. std::sort(sorted_attributes.begin(), sorted_attributes.end()); // Build the JavaDoc comment for the Styleable array. This has references to child attributes // and what possible values can be used for them. const size_t attr_count = sorted_attributes.size(); if (out_class_def != nullptr && attr_count > 0) { std::stringstream styleable_comment; if (!styleable.GetComment().empty()) { styleable_comment << styleable.GetComment() << "\n"; } else { // Apply a default intro comment if the styleable has no comments of its own. styleable_comment << "Attributes that can be used with a " << array_field_name << ".\n"; } styleable_comment << "

Includes the following attributes:

\n" "\n" "\n" "\n" "\n"; // Removed and hidden attributes are public but hidden from the documentation, so don't emit // them as part of the class documentation. std::vector documentation_attrs = sorted_attributes; auto documentation_remove_iter = std::remove_if(documentation_attrs.begin(), documentation_attrs.end(), [&](StyleableAttr entry) -> bool { if (SkipSymbol(entry.symbol)) { return true; } const StringPiece attr_comment_line = entry.symbol.value().attribute->GetComment(); return attr_comment_line.contains("@removed") || attr_comment_line.contains("@hide"); }); documentation_attrs.erase(documentation_remove_iter, documentation_attrs.end()); // Build the table of attributes with their links and names. for (const StyleableAttr& entry : documentation_attrs) { const ResourceName& attr_name = entry.attr_ref->name.value(); styleable_comment << ""; // Only use the comment up until the first '.'. This is to stay compatible with // the way old AAPT did it (presumably to keep it short and to avoid including // annotations like @hide which would affect this Styleable). StringPiece attr_comment_line = entry.symbol.value().attribute->GetComment(); styleable_comment << "\n"; } styleable_comment << "
AttributeDescription
{@link #" << entry.field_name << " " << (!attr_name.package.empty() ? attr_name.package : package_name_to_generate) << ":" << attr_name.entry << "}" << AnnotationProcessor::ExtractFirstSentence(attr_comment_line) << "
\n"; // Generate the @see lines for each attribute. for (const StyleableAttr& entry : documentation_attrs) { styleable_comment << "@see #" << entry.field_name << "\n"; } array_def->GetCommentBuilder()->AppendComment(styleable_comment.str()); } if (r_txt_printer != nullptr) { r_txt_printer->Print("int[] styleable ").Print(array_field_name).Print(" {"); } // Add the ResourceIds to the array member. for (size_t i = 0; i < attr_count; i++) { const StyleableAttr& attr = sorted_attributes[i]; std::string r_txt_contents; if (attr.symbol && attr.symbol.value().is_dynamic) { if (!attr.attr_ref->name) { error_ = "unable to determine R.java field name of dynamic resource"; return false; } const FieldReference field_name = GetRFieldReference(attr.attr_ref->name.value(), package_name_to_generate); array_def->AddElement(field_name); r_txt_contents = field_name.ref; } else { const ResourceId attr_id = attr.attr_ref->id.value_or_default(ResourceId(0)); array_def->AddElement(attr_id); r_txt_contents = to_string(attr_id); } if (r_txt_printer != nullptr) { if (i != 0) { r_txt_printer->Print(","); } r_txt_printer->Print(" ").Print(r_txt_contents); } } if (r_txt_printer != nullptr) { r_txt_printer->Println(" }"); } // Add the Styleable array to the Styleable class. if (out_class_def != nullptr) { out_class_def->AddMember(std::move(array_def)); } // Now we emit the indices into the array. for (size_t i = 0; i < attr_count; i++) { const StyleableAttr& styleable_attr = sorted_attributes[i]; if (SkipSymbol(styleable_attr.symbol)) { continue; } if (out_class_def != nullptr) { StringPiece comment = styleable_attr.attr_ref->GetComment(); if (styleable_attr.symbol.value().attribute && comment.empty()) { comment = styleable_attr.symbol.value().attribute->GetComment(); } if (comment.contains("@removed")) { // Removed attributes are public but hidden from the documentation, so // don't emit them as part of the class documentation. continue; } const ResourceName& attr_name = styleable_attr.attr_ref->name.value(); StringPiece package_name = attr_name.package; if (package_name.empty()) { package_name = package_name_to_generate; } std::unique_ptr index_member = util::make_unique(sorted_attributes[i].field_name, static_cast(i)); AnnotationProcessor* attr_processor = index_member->GetCommentBuilder(); if (!comment.empty()) { attr_processor->AppendComment("

\n@attr description"); attr_processor->AppendComment(comment); } else { std::stringstream default_comment; default_comment << "

This symbol is the offset where the " << "{@link " << package_name << ".R.attr#" << TransformToFieldName(attr_name.entry) << "}\n" << "attribute's value can be found in the " << "{@link #" << array_field_name << "} array."; attr_processor->AppendComment(default_comment.str()); } attr_processor->AppendNewLine(); AddAttributeFormatDoc(attr_processor, styleable_attr.symbol.value().attribute.get()); attr_processor->AppendNewLine(); attr_processor->AppendComment( StringPrintf("@attr name %s:%s", package_name.data(), attr_name.entry.data())); out_class_def->AddMember(std::move(index_member)); } if (r_txt_printer != nullptr) { r_txt_printer->Println( StringPrintf("int styleable %s %zd", sorted_attributes[i].field_name.c_str(), i)); } } return true; } void JavaClassGenerator::ProcessResource(const ResourceNameRef& name, const ResourceId& id, const ResourceEntry& entry, ClassDefinition* out_class_def, MethodDefinition* out_rewrite_method, text::Printer* r_txt_printer) { ResourceId real_id = id; if (context_->GetMinSdkVersion() < SDK_O && name.type == ResourceType::kId && id.package_id() > kAppPackageId) { // Workaround for feature splits using package IDs > 0x7F. // See b/37498913. real_id = ResourceId(kAppPackageId, id.package_id(), id.entry_id()); } const std::string field_name = TransformToFieldName(name.entry); if (out_class_def != nullptr) { auto resource_member = util::make_unique(field_name, real_id, entry.visibility.staged_api); // Build the comments and annotations for this entry. AnnotationProcessor* processor = resource_member->GetCommentBuilder(); // Add the comments from any tags. if (entry.visibility.level != Visibility::Level::kUndefined) { processor->AppendComment(entry.visibility.comment); } // Add the comments from all configurations of this entry. for (const auto& config_value : entry.values) { processor->AppendComment(config_value->value->GetComment()); } // If this is an Attribute, append the format Javadoc. if (!entry.values.empty()) { if (Attribute* attr = ValueCast(entry.values.front()->value.get())) { // We list out the available values for the given attribute. AddAttributeFormatDoc(processor, attr); } } out_class_def->AddMember(std::move(resource_member)); } if (r_txt_printer != nullptr) { r_txt_printer->Print("int ") .Print(to_string(name.type)) .Print(" ") .Print(field_name) .Print(" ") .Println(real_id.to_string()); } if (out_rewrite_method != nullptr) { const StringPiece& type_str = to_string(name.type); out_rewrite_method->AppendStatement( StringPrintf("%s.%s = (%s.%s & 0x00ffffff) | packageIdBits;", type_str.data(), field_name.data(), type_str.data(), field_name.data())); } } Maybe JavaClassGenerator::UnmangleResource(const StringPiece& package_name, const StringPiece& package_name_to_generate, const ResourceEntry& entry) { if (SkipSymbol(entry.visibility.level)) { return {}; } std::string unmangled_package; std::string unmangled_name = entry.name; if (NameMangler::Unmangle(&unmangled_name, &unmangled_package)) { // The entry name was mangled, and we successfully unmangled it. // Check that we want to emit this symbol. if (package_name_to_generate != unmangled_package) { // Skip the entry if it doesn't belong to the package we're writing. return {}; } } else if (package_name_to_generate != package_name) { // We are processing a mangled package name, // but this is a non-mangled resource. return {}; } return {std::move(unmangled_name)}; } bool JavaClassGenerator::ProcessType(const StringPiece& package_name_to_generate, const ResourceTablePackage& package, const ResourceTableType& type, ClassDefinition* out_type_class_def, MethodDefinition* out_rewrite_method_def, Printer* r_txt_printer) { for (const auto& entry : type.entries) { const Maybe unmangled_name = UnmangleResource(package.name, package_name_to_generate, *entry); if (!unmangled_name) { continue; } // Create an ID if there is one (static libraries don't need one). ResourceId id; if (entry->id) { id = entry->id.value(); } // We need to make sure we hide the fact that we are generating kAttrPrivate attributes. const ResourceNameRef resource_name( package_name_to_generate, type.type == ResourceType::kAttrPrivate ? ResourceType::kAttr : type.type, unmangled_name.value()); // Check to see if the unmangled name is a valid Java name (not a keyword). if (!IsValidSymbol(unmangled_name.value())) { std::stringstream err; err << "invalid symbol name '" << resource_name << "'"; error_ = err.str(); return false; } if (resource_name.type == ResourceType::kStyleable) { CHECK(!entry->values.empty()); const auto styleable = reinterpret_cast(entry->values.front()->value.get()); if (!ProcessStyleable(resource_name, id, *styleable, package_name_to_generate, out_type_class_def, out_rewrite_method_def, r_txt_printer)) { return false; } } else { ProcessResource(resource_name, id, *entry, out_type_class_def, out_rewrite_method_def, r_txt_printer); } } return true; } bool JavaClassGenerator::Generate(const StringPiece& package_name_to_generate, OutputStream* out, OutputStream* out_r_txt) { return Generate(package_name_to_generate, package_name_to_generate, out, out_r_txt); } static void AppendJavaDocAnnotations(const std::vector& annotations, AnnotationProcessor* processor) { for (const std::string& annotation : annotations) { std::string proper_annotation = "@"; proper_annotation += annotation; processor->AppendComment(proper_annotation); } } bool JavaClassGenerator::Generate(const StringPiece& package_name_to_generate, const StringPiece& out_package_name, OutputStream* out, OutputStream* out_r_txt) { ClassDefinition r_class("R", ClassQualifier::kNone, true); std::unique_ptr rewrite_method; std::unique_ptr r_txt_printer; if (out_r_txt != nullptr) { r_txt_printer = util::make_unique(out_r_txt); } // Generate an onResourcesLoaded() callback if requested. if (out != nullptr && options_.rewrite_callback_options) { rewrite_method = util::make_unique("public static void onResourcesLoaded(int p)"); for (const std::string& package_to_callback : options_.rewrite_callback_options.value().packages_to_callback) { rewrite_method->AppendStatement( StringPrintf("%s.R.onResourcesLoaded(p);", package_to_callback.data())); } rewrite_method->AppendStatement("final int packageIdBits = p << 24;"); } const bool is_public = (options_.types == JavaClassGeneratorOptions::SymbolTypes::kPublic); for (const auto& package : table_->packages) { for (const auto& type : package->types) { if (type->type == ResourceType::kAttrPrivate || type->type == ResourceType::kMacro) { // We generate kAttrPrivate as part of the kAttr type, so skip them here. // Macros are not actual resources, so skip them as well. continue; } // Stay consistent with AAPT and generate an empty type class if the R class is public. const bool force_creation_if_empty = is_public; std::unique_ptr class_def; if (out != nullptr) { class_def = util::make_unique( to_string(type->type), ClassQualifier::kStatic, force_creation_if_empty); } if (!ProcessType(package_name_to_generate, *package, *type, class_def.get(), rewrite_method.get(), r_txt_printer.get())) { return false; } if (type->type == ResourceType::kAttr) { // Also include private attributes in this same class. if (const ResourceTableType* priv_type = package->FindType(ResourceType::kAttrPrivate)) { if (!ProcessType(package_name_to_generate, *package, *priv_type, class_def.get(), rewrite_method.get(), r_txt_printer.get())) { return false; } } } if (out != nullptr && type->type == ResourceType::kStyleable && is_public) { // When generating a public R class, we don't want Styleable to be part // of the API. It is only emitted for documentation purposes. class_def->GetCommentBuilder()->AppendComment("@doconly"); } if (out != nullptr) { AppendJavaDocAnnotations(options_.javadoc_annotations, class_def->GetCommentBuilder()); r_class.AddMember(std::move(class_def)); } } } if (rewrite_method != nullptr) { r_class.AddMember(std::move(rewrite_method)); } if (out != nullptr) { AppendJavaDocAnnotations(options_.javadoc_annotations, r_class.GetCommentBuilder()); ClassDefinition::WriteJavaFile(&r_class, out_package_name, options_.use_final, !is_public, out); } return true; } } // namespace aapt