-reportconfig plugin-def ( ',' plugin-def )*

The purpose of the -reportconfig instruction is to configure the content of the reports exported with the -exportreport instruction.

When a report is generated, a set of plugins is used to extract a specific piece of data from the source (for example, the information contain in metatypes from a bundle source). Those plugins are generally designed to not require a configuration and are silently ignored if they do not find any data, thus, this instruction should rarely be used.

Additional plugins can be declared and configured with the -plugin.* instruction and will be available for all your reports, however the -reportconfig instruction gives more control on the plugins that should be used when generating a specific report. This instruction diverges from the -plugins.* instruction as you can declare named configuration, for example -reportconfig.api-bundle:... will have the name api-bundle that you can then use for a specific report -exportreport:file.json;configName=api-bundle. In addition, this instruction allows to declare plugins with a short name instead of the canonical name of the plugin class (importFile instead of biz.aQute.bnd.reporter.plugins.entries.any.ImportResourcePlugin).

See -exportreport instruction documentation.

Syntax

-reportconfig.xxx  ::= plugin-def ( ',' plugin-def ) *
plugin-def         ::= plugin | 'clearDefaults'
plugin             ::= ( qname | plugin-name ) ( ';' parameters ) *
plugin-name        ::= extended

where xxx is the name of the configuration.

Example

One use case is when you want a specific resource from a bundle in the report but where there is no plugins to extract it. For this you can use the importJarFile plugin which need the path to the resource inside the bundle and will import it into the report.

For example, if you need blueprint data:

bnb.bnd

-reportconfig.blueprint: importJarFile;path=OSGI-INF/blueprint/component.xml
-exportreport: metadata.json;configName=blueprint

Clean configuration

When you set a -reportconfig.xxx instruction, a list of default plugins will be added to the specified list. If you do not want the default plugins you can use the special property clearDefaults:

bnb.bnd

-reportconfig.blueprint: \
   importJarFile;path=OSGI-INF/blueprint/component.xml, \
   clearDefaults

Plugins

This section describes the available plugins in Bnd, additional plugins may be provided by a specific build tool.

All plugins have the entryName property which can be set to override the name under which data will be aggregated into the reports (this corresponds to a tag name when serialised in XML):

 -reportconfig.bundle: metatypes;entryName=serviceConfigs

Any Entry

This plugin allows the user to define an arbitrary entry.

• Short name: anyEntry
• Properties:
  • key: the name under which the value will be available in the report.
  • value: the value of the entry.
• Default Plugin: no

-reportconfig.api-bundle:anyEntry;key=bundleType;value=api

Import File

This plugin allows to add a local or remote file to the report. The type of the file can be: properties, manifest, XML and JSON.

• Short name: importFile
• Properties:
  • url: URL to the file.
  • type: The type of the file. (optional)
• Default Plugin: no

-reportconfig.bundle:importFile;url=http://<...>/myFile.json

Import Jar File

This plugin allows to add a file contains in a bundle to the report. The type of the file can be: properties, manifest, XML and JSON.

• Short name: importJarFile
• Properties:
  • path: Path from the root of the Jar.
  • type: The type of the file. (optional)
• Default Plugin: no

-reportconfig.bundle:

CommonInfo

Add some common data to the report. If data are extracted from the workspace, the following properties will be read in the build.bnd file: ws-name, ws-description, ws-version, ws-icons, ws-docURL, ws-updateLocation, ws-licenses, ws-developers, ws-scm, ws-copyright, ws-vendor, ws-contactAddress; otherwise, the corresponding headers will be read. If data are extracted from a project, the above properties will be read in the bnd.bnd file but with a p- prefix, such as p-contactAddress.

• Short name: commonInfo
• Default Plugin: yes

Manifest

Add the OSGI headers to the report.

• Short name: manifest
• Default Plugin: yes

Components

Add a list of the declarative services.

• Short name: components
• Default Plugin: yes

Metatypes

Add a list of the metatypes.

• Short name: metatypes
• Default Plugin: yes

File Name

Add the file name or the folder name in which the source is backed up.

• Short name: fileName
• Default Plugin: yes

Bundles

Add a list of bundle data (for example, the bundles built by a project).

• Short name: bundles
• Properties:
  • useConfig: The configuration name used when generating the data. (optional)
  • excludes: A list of bundle symbolic names to exclude. (optional)
• Default Plugin: yes

-reportconfig.project:bundles;useConfig=api-bundle;excludes="com.domain.product.provider"

Code Snippets

Add a list of code snippet extracted from source files in a project. By default, source files containing code snippets must be located in a <root test source dir>/examples folder and its sub directories (eg; src/test/java/examples/**). The actual supported file types are: java.

Code snippets can either be a single sample code with a title and a description or have multiple steps.

• Short name: codeSnippets
• Properties:
  • path: The directory path from which code snippets will be looked up. (optional)
• Default Plugin: yes

Java Code Snippets

You can either export a full type or a method. For the snippet to be extracted you must add a comment block to the type or the method. The comment must contain the ${snippet } tag with the following optional properties:

• title (String): A title for the code snippet.
• description (String): A short description of the code snippet.
• includeDeclaration (Boolean): If true, the type declaration (or the method declaration) will be include, otherwise only its content. Default is true.
• includeImports (Boolean): If true, the imports declration will be include. Default is true.
• groupName (String): A user defined group name. If set, it will turn the actual snippet into a snippet with multiple steps, only the title and the description considered then and the snippet children must reference its groupName in their parentGroup property.
• parentGroup (String): The parent group name. If set, it will make the actual snippet a step in the referenced snippet group.
• id (String): A user defined id of the snippet. By default, the Id is the type name or the method name, optionally appended by a counting starting from 1 if not unique (eg; MyType, MyType1, etc).

Here is an example illustrating a code snippet with steps:

/**
 * ${snippet title=How to Print Something in Java, description="In this example we will show how to
 * print a string to the console.", groupName=print} 
 */
public class PrintExample {

  /**
   * ${snippet title=Print No New Line, description="Here, we print without a new line at the end.",
   * parentGroup=print, includeDeclaration=false} 
   */
  public void printNoNewLine() {
    System.out.print("Hello");
  }

  /**
   * ${snippet title=Print With New Line, description="Here, we print with a new line at the end.",
   * parentGroup=print, includeDeclaration=false} 
   */
  public void printWithNewLine() {
    System.out.println("Hello");
  }
}

Which will result in the following json object:

{ 
   "id": "PrintExample",
   "title":"How to Print Something in Java",
   "description":"In this example we will show how to print a string to the console.",
   "steps":[
      {
         "id": "printNoNewLine",
         "title":"Print No New Line",
         "description":"Here, we print without a new line at the end.",
         "programmingLangague":"java",
         "codeSnippet":"System.out.print(\"Hello\");"
      },
      {
         "id": "printWithNewLine",
         "title":"Print With New Line",
         "description":"Here, we print with a new line at the end.",
         "programmingLangague":"java",
         "codeSnippet":"System.out.println(\"Hello\");"
      }
   ]
}

Projects

Add a list of project data (for example, the projects built by the workspace).

• Short name: projects
• Properties:
  • useConfig: The configuration name used when generating the data. (optional)
  • excludes: A list of project names to exclude.
• Default Plugin: yes

-reportconfig.ws:projects;useConfig=bnd-proj;excludes="maven-index"

Maven Coordinate

Add the maven coordinate of the bundle (extracted from the pom.properties file).

• Short name: mavenCoordinate
• Properties: no
• Default Plugin: yes