--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.
+.. http://creativecommons.org/licenses/by/4.0
+
+
+APEX Developer Guide
+********************
+
+.. contents::
+ :depth: 3
+
+Build APEX from Source
+^^^^^^^^^^^^^^^^^^^^^^
+
+Introduction to building APEX
+-----------------------------
+
+ .. container:: paragraph
+
+ APEX is written 100% in Java and uses `Apache
+ Maven <https://maven.apache.org/>`__ as the build system.
+ The requirements for building APEX are:
+
+ .. container:: ulist
+
+ - An installed Java development kit for Java version 8
+ or higher
+
+ .. container:: ulist
+
+ - To install a Java SDK please follow these
+ guidelines `Oracle Java 8
+ SDK <https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html>`__.
+
+ - Maven 3
+
+ .. container:: ulist
+
+ - To get Maven 3 running please follow the
+ guidelines for
+ `Download <https://maven.apache.org/download.cgi>`__
+ and
+ `Install <https://maven.apache.org/install.html>`__,
+ and `Run <https://maven.apache.org/run.html>`__
+ Maven
+
+ - A clone of the APEX source repositories
+
+ .. container:: paragraph
+
+ To get a clone of the APEX source repositories, please
+ see the APEX Installation Guide or the APEX User manual.
+
+ .. container:: paragraph
+
+ One all requirements are in place, APEX can be build.
+ There are several different artifacts one can create
+ building APEX, most of them defined in their own
+ *profile*. APEX can also be build in a standard way with
+ standard tests (``mvn clean install``) or without
+ standard tests (``mvn clean install -DskipTests``).
+
+ .. container:: paragraph
+
+ The examples in this document assume that the APEX source
+ repositories are cloned to:
+
+ .. container:: ulist
+
+ - Unix, Cygwin: ``/usr/local/src/apex``
+
+ - Windows: ``C:\dev\apex``
+
+ - Cygwin: ``/cygdrive/c/dev/apex``
+
+ .. important::
+ A Build requires ONAP Nexus
+ APEX has a dependency to ONAP parent projects. You might need to adjust your Maven M2 settings. The most current
+ settings can be found in the ONAP oparent repo: `Settings <https://git.onap.org/oparent/plain/settings.xml>`__.
+
+ .. important::
+
+ A Build needs Space
+ Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full
+ distribution and 1-2 GB for the downloaded dependencies
+
+ .. important::
+ A Build requires Internet (for first build to download all dependencies and plugins)
+ During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven
+ repository. The first standard build (and any first specific build) requires Internet access to download those
+ dependencies.
+
+ .. important::
+ Building RPM distributions
+ RPM images are only build if the ``rpm`` package is installed (Unix). To install ``rpm``
+ run ``sudo apt-get install rpm``, then build APEX.
+
+Standard Build
+--------------
+
+ .. container:: paragraph
+
+ Use Maven to for a standard build without any tests.
+
+ +-----------------------------------+------------------------------------+
+ | Unix, Cygwin | Windows |
+ +===================================+====================================+
+ | :: | :: |
+ | | |
+ | >c: | # cd /usr/local/src/apex |
+ | >cd \dev\apex | # mvn clean install -DskipTests |
+ | >mvn clean install -DskipTests | |
+ | | |
+ +-----------------------------------+------------------------------------+
+
+.. container:: paragraph
+
+ The build takes about 6 minutes on a standard development laptop. It
+ should run through without errors, but with a lot of messages from
+ the build process.
+
+.. container:: paragraph
+
+ When Maven is finished with the build, the final screen should look
+ similar to this (omitting some ``success`` lines):
+
+.. container:: listingblock
+
+ .. code:: bash
+ :number-lines:
+
+ [INFO] tools .............................................. SUCCESS [ 0.248 s]
+ [INFO] tools-common ....................................... SUCCESS [ 0.784 s]
+ [INFO] simple-wsclient .................................... SUCCESS [ 3.303 s]
+ [INFO] model-generator .................................... SUCCESS [ 0.644 s]
+ [INFO] packages ........................................... SUCCESS [ 0.336 s]
+ [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
+ [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
+ [INFO] ------------------------------------------------------------------------
+ [INFO] BUILD SUCCESS
+ [INFO] ------------------------------------------------------------------------
+ [INFO] Total time: 03:43 min
+ [INFO] Finished at: 2018-09-03T11:56:01+01:00
+ [INFO] ------------------------------------------------------------------------
+
+.. container:: paragraph
+
+ The build will have created all artifacts required for an APEX
+ installation. The following example show how to change to the target
+ directory and how it should look like.
+
++-----------------------------------------------------------------------------------------------------------------------------+
+| Unix, Cygwin |
++=============================================================================================================================+
+| .. container:: |
+| |
+| .. container:: listingblock |
+| |
+| .. code:: bash |
+| :number-lines: |
+| |
+| # cd packages/apex-pdp-package-full/target |
+| # ls -l |
+| -rwxrwx---+ 1 esvevan Domain Users 772 Sep 3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes* |
+| -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb* |
+| -rwxrwx---+ 1 esvevan Domain Users 15633 Sep 3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar* |
+| -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep 3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz* |
+| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 archive-tmp/ |
+| -rwxrwx---+ 1 esvevan Domain Users 89 Sep 3 11:54 checkstyle-cachefile* |
+| -rwxrwx---+ 1 esvevan Domain Users 10621 Sep 3 11:54 checkstyle-checker.xml* |
+| -rwxrwx---+ 1 esvevan Domain Users 584 Sep 3 11:54 checkstyle-header.txt* |
+| -rwxrwx---+ 1 esvevan Domain Users 86 Sep 3 11:54 checkstyle-result.xml* |
+| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 classes/ |
+| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 dependency-maven-plugin-markers/ |
+| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 etc/ |
+| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 examples/ |
+| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:55 install_hierarchy/ |
+| drwxrwx---+ 1 esvevan Domain Users 0 Sep 3 11:54 maven-archiver/ |
++-----------------------------------------------------------------------------------------------------------------------------+
+
++-----------------------------------------------------------------------------------------------------------------------------+
+| Windows |
++=============================================================================================================================+
+| .. container:: |
+| |
+| .. container:: listingblock |
+| |
+| .. code:: bash |
+| :number-lines: |
+| |
+| >cd packages\apex-pdp-package-full\target |
+| >dir |
+| |
+| 03/09/2018 11:55 <DIR> . |
+| 03/09/2018 11:55 <DIR> .. |
+| 03/09/2018 11:55 146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz |
+| 03/09/2018 11:55 146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb |
+| 03/09/2018 11:54 15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar |
+| 03/09/2018 11:55 772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes |
+| 03/09/2018 11:54 <DIR> archive-tmp |
+| 03/09/2018 11:54 89 checkstyle-cachefile |
+| 03/09/2018 11:54 10,621 checkstyle-checker.xml |
+| 03/09/2018 11:54 584 checkstyle-header.txt |
+| 03/09/2018 11:54 86 checkstyle-result.xml |
+| 03/09/2018 11:54 <DIR> classes |
+| 03/09/2018 11:54 <DIR> dependency-maven-plugin-markers |
+| 03/09/2018 11:54 <DIR> etc |
+| 03/09/2018 11:54 <DIR> examples |
+| 03/09/2018 11:55 <DIR> install_hierarchy |
+| 03/09/2018 11:54 <DIR> maven-archiver |
+| 8 File(s) 292,652,686 bytes |
+| 9 Dir(s) 14,138,720,256 bytes free |
++-----------------------------------------------------------------------------------------------------------------------------+
+
+
+Checkstyle with Maven
+---------------------
+
+ .. container:: paragraph
+
+ The codestyle for all APEX java projects can be checked
+ automatically. The checks include empty or non-existing Javadocs.
+ Any checkstyle run should complete without any errors, some
+ warnings are acceptable.
+
+ .. container:: paragraph
+
+ To run checkstyle on an APEX Maven project use:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ mvn checkstyle:check
+
+ .. container:: paragraph
+
+ To run checkstyle on all modules use:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ mvn checkstyle:checkstyle -DapexAll
+
+Build with standard Tests
+-------------------------
+
+ .. container:: paragraph
+
+ Use Maven to for a standard build with standard tests.
+
+ .. important::
+ Some tests have specific timing Requirements
+ Some of the tests have very specific timing requirements. If run on a low-powered build machine, or if the build
+ machine is on high load, those tests might fail and the whole build might fail as well. If this happens, reduce the load
+ on your build machine and restart the build.
+
+ +-----------------------------------+-----------------------------------+
+ | Unix, Cygwin | Windows |
+ +===================================+===================================+
+ | .. container:: | .. container:: |
+ | | |
+ | .. container:: content | .. container:: content |
+ | | |
+ | .. code:: bash | .. code:: bash |
+ | :number-lines: | :number-lines: |
+ | | |
+ | >c: | # cd /usr/local/src/apex |
+ | >cd \dev\apex | # mvn clean install |
+ | >mvn clean install | |
+ +-----------------------------------+-----------------------------------+
+
+
+.. container:: paragraph
+
+ The build takes about 10 minutes with tests on a standard development
+ laptop. It should run through without errors, but with a lot of
+ messages from the build process. If build with tests (i.e. without
+ ``-DskipTests``), there will be error messages and stack trace prints
+ from some tests. This is normal, as long as the build finishes
+ successful.
+
+Build with all Tests
+--------------------
+
+ .. container:: paragraph
+
+ Use Maven to for a standard build with *all* tests.
+
+ .. important::
+ Some tests have specific timing Requirements.
+ Some of the tests have very specific timing requirements. If run on a low-powered build machine, or if the build
+ machine is on high load, those tests might fail and the whole build might fail as well. If this happens, reduce the load
+ on your build machine and restart the build.
+
+ .. important::
+ Might require specific software.
+ When running all tests, some modules require specific software installed on the build machine. For instance,
+ testing the full capabilities of context (with distribution and persistence) will require Hazelcast and Infinispan
+ installed on the build machine.
+
+ +----------------------------------------------+----------------------------------------------+
+ | Unix, Cygwin | Windows |
+ +==============================================+==============================================+
+ | .. container:: | .. container:: |
+ | | |
+ | .. container:: content | .. container:: content |
+ | | |
+ | .. code:: bash | .. code:: bash |
+ | :number-lines: | :number-lines: |
+ | | |
+ | >c: | # cd /usr/local/src/apex |
+ | >cd \dev\apex | # mvn clean install -DallTests |
+ | >mvn clean install -DallTests | |
+ +----------------------------------------------+----------------------------------------------+
+
+Build with all Components
+-------------------------
+
+ .. container:: paragraph
+
+ A standard APEX build will not build all components. Some parts
+ are for specific deployments, only. Use Maven to for a standard
+ build with *all* components.
+
+ .. important::
+ Might require specific software.
+ When building all components, some modules require specific software installed on the build machine.
+
+ +----------------------------------------------+----------------------------------------------+
+ | Unix, Cygwin | Windows |
+ +==============================================+==============================================+
+ | .. container:: | .. container:: |
+ | | |
+ | .. container:: content | .. container:: content |
+ | | |
+ | .. code:: bash | .. code:: bash |
+ | :number-lines: | :number-lines: |
+ | | |
+ | >c: | # cd /usr/local/src/apex |
+ | >cd \dev\apex | # mvn clean install -DapexAll |
+ | >mvn clean install -DapexAll | |
+ +----------------------------------------------+----------------------------------------------+
+
+
+Build the APEX Documentation
+----------------------------
+
+ .. container:: paragraph
+
+ The APEX Maven build also includes stand-alone documentations,
+ such as the HowTo documents, the Installation Guide, and the User
+ Manual. Use Maven to build the APEX Documentation. The Maven
+ options ``-N`` prevents Maven to go through all APEX modules,
+ which is not necessary for the documentation. The final documents
+ will be in ``target/generated-docs`` (Windows:
+ ``target\generated-docs``). The *HTML* documents are in the
+ ``html/`` folder, the *PDF* documents are in the ``pdf/`` folder.
+ Once the documentation is build, copy the *HTML* and *PDF*
+ documents to a folder of choice
+
+ +-------------------------------------------------------+--------------------------------------------------------+
+ | Unix, Cygwin | Windows |
+ +=======================================================+========================================================+
+ | .. container:: | .. container:: |
+ | | |
+ | .. container:: content | .. container:: content |
+ | | |
+ | .. code:: bash | .. code:: bash |
+ | :number-lines: | :number-lines: |
+ | | |
+ | >c: | # cd /usr/local/src/apex |
+ | >cd \dev\apex | # mvn clean generate-resources -N -DapexDocs |
+ | >mvn clean generate-resources -N -DapexDocs | |
+ +-------------------------------------------------------+--------------------------------------------------------+
+
+Build APEX Site
+---------------
+
+ .. container:: paragraph
+
+ The APEX Maven build comes with full support to build a web site
+ using Maven Site. Use Maven to build the APEX Site. Stage the APEX
+ web site. The target folder for the staged site is
+
+ .. container:: ulist
+
+ - Unix: ``/usr/local/src/apex/target/ad-site``
+
+ - Windows: ``C:\dev\apex\target\ad-site``
+
+ - Cygwin: ``/cygdrive/c/dev/apex/target/ad-site``
+
+ .. container:: paragraph
+
+ Once the web site is staged, copy the full site to a folder of
+ choice or into a web server.
+
+ .. important::
+ Building a Site takes Time.
+ Building and staging the APEX web site can take very long. The stand-alone documentation will take about 2 minutes. The
+ sites for all modules and projects and the main APEX site can take between 10-30 minutes depending on your build machine (~10 minutes
+ without generating source and test-source reports, closer to 30 minutes with all reports).
+
+ .. container:: paragraph
+
+ Start the build deleting the staging directory that might have
+ been created by a previous site build. Then go to the APEX
+ packaging directory.
+
+ +--------------------------------+-----------------------------------+----------------------------------+
+ | Unix | Windows | Cygwin |
+ +================================+===================================+==================================+
+ | .. container:: | .. container:: | .. container:: |
+ | | | |
+ | .. container:: content | .. container:: content | .. container:: content |
+ | | | |
+ | .. code:: bash | .. code:: bash | .. code:: bash |
+ | :number-lines: | :number-lines: | :number-lines: |
+ | | | |
+ | cd /usr/local/src/apex | c: | cd /cygdrive/c/dev/apex |
+ | rm -fr target/ad-site | cd \dev\apex | rm -fr target/ad-site |
+ | | rmdir /s/q target\ad-site | |
+ +--------------------------------+-----------------------------------+----------------------------------+
+
+ .. container:: paragraph
+
+ the workflow for building a complete site then is as follows:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ mvn clean -DapexAll (1)
+ mvn install -DskipTests (2)
+ mvn generate-resources -N -DapexDocs (3)
+ mvn initialize site:attach-descriptor site site:stage -DapexSite (4)
+
+ .. container:: olist arabic
+
+ #. First clean all modules to remove any site artifacts, use the
+ *apexXtext* profile to make sure these modules are processed as
+ well
+
+ #. Next run a simple install without tests
+
+ #. Now generate the APEX stand -alone documentation, they are in
+ the local package only so we can use the *-N* switch
+
+ #. Last build the actual sites and stage (copy to the staging
+ directory) with the profile *apexSite* (do not forget the
+ initialize goal, otherwise the staging directory will not be
+ correctly set and sites are staged in every model in a
+ directory called ``docs``).
+
+ .. container:: paragraph
+
+ If you want to build the site for a particular project for
+ testing, the Maven command is simpler. Since only the main project
+ has APEX documentation (stand-alone), you can use Maven as follow.
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ mvn clean site -DapexSite
+
+ .. container:: paragraph
+
+ If you want to stage the tested site, then use
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ mvn clean initialize site:attach-descriptor site site:stage -DapexSite
+
+APEX Codestyle
+^^^^^^^^^^^^^^
+
+Introduction: APEX Codestyle
+----------------------------
+
+ .. container:: paragraph
+
+ This page describes how to apply a code style to the APEX
+ Java projects. The provided code templates are guidelines
+ and are provided for references and as examples. We will not
+ engage in "holy war" on style for coding. As long as the
+ style of a particular block of code is understandable,
+ consistent, and readable, please feel free to adapt or
+ modify these guides or use other guides as you see fit.
+
+ .. container:: paragraph
+
+ The JAutoDoc and Checkstyle Eclipse Plugins and tools are
+ useful and remove a lot of the tedium from code
+ documentation. Use them to check your code and please fix
+ any issues they identify with your code.
+
+ .. container:: paragraph
+
+ Since APEX is part of ONAP, the general ONAP rules and
+ guideliness for development do apply. Please see `ONAP
+ Wiki <https://wiki.onap.org/display/DW/Developing+ONAP>`__
+ for details.
+
+Java coding Rules
+-----------------
+
+ .. container:: ulist
+
+ - APEX is (in large parts) a platform (or middleware), so
+ `Software Design
+ Patterns <https://en.wikipedia.org/wiki/Software_design_pattern>`__
+ are a good thing
+
+ - The `Solid
+ Principles <https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)>`__
+ apply
+
+ - Avoid class fields scoped as ``protected``
+
+ .. container:: ulist
+
+ - They break a lot of good design rules, e.g. most
+ SOLID rules
+
+ - For a discussion see this `Stackoverflow
+ Question <https://softwareengineering.stackexchange.com/questions/162643/why-is-clean-code-suggesting-avoiding-protected-variables>`__
+
+ - If you absolutely need ``protected`` class fields they
+ should be ``final``
+
+ - Avoid ``default`` scope for class fields and methods
+
+ .. container:: ulist
+
+ - For fields: use ``public`` or ``private`` (see also
+ above)
+
+ - For methods: use ``public`` for general use,
+ ``protected`` for specialization using inheritance
+ (ideally ``final``), ``private`` for everything
+ else
+
+ - Method parameters that are not changed in the method
+ should be marked ``final``
+
+ - Every package must have a ``package-info.java`` file with
+ an appropriate description, minimum a descriptive one
+ liner
+
+ - Every class must have
+
+ .. container:: ulist
+
+ - The common header (copyright, file, date)
+
+ - Javadoc header for the class with description of
+ the class and author
+
+ - Javadoc for *all public\_* fields
+
+ - If possible, Javadoc for *private* fields, at least
+ some documentation for private fields
+
+ - Javadoc for *all* methods
+
+ - All project must build with all tests on Unix, Windows,
+ *and* Cygwin
+
+ .. container:: ulist
+
+ - Support all line endings in files, e.g. ``\n`` and
+ ``\r\n``
+
+ - Be aware of potential differences in exception
+ messages, if testing against a message
+
+ - Support all types of paths: Unix with ``/``,
+ Windows with an optinal drive ``C:\`` and ``\``,
+ Cygwin with mixed paths
+
+Eclipse Plugin: JAutodoc
+------------------------
+
+ .. container:: paragraph
+
+ This plugin is a helper plugin for writing Javadoc. It will
+ automatically create standard headers on files, create
+ package-info.java files and will put in remarkably good stub
+ Javadoc comments in your code, using class names and method
+ names as hints.
+
+ .. container:: paragraph
+
+ Available from the Eclipse Marketplace. In Eclipse
+ Help→Eclipse Marketplace… and type ``JAutodoc``. Select
+ JAutodoc when the search returns and install it.
+
+ .. container:: paragraph
+
+ You must configure JAutoDoc in order to get the most out of
+ it. Ideally JAutoDoc should be configured with templates
+ that cooperate with the inbuilt Eclipse Code Formatter for
+ best results.
+
+Eclipse Plugin: Checkstyle
+--------------------------
+
+ .. container:: paragraph
+
+ This plugin integrates
+ `Checkstyle <http://checkstyle.sourceforge.net/>`__ into
+ Eclipse. It will check your code and flag any checkstyle
+ issues as warnings in the code.
+
+ .. container:: paragraph
+
+ Available from the Eclipse Marketplace. In Eclipse
+ Help→Eclipse Marketplace… and type "Checkstyle". Select
+ "Checkstyle Plug-in" when the search returns and install it.
+ Note that "Checkstyle Plug-in" may not be the first result
+ in the list of items returned.
+
+ .. container:: paragraph
+
+ For APEX, the ONAP checkstyle rules do apply. The
+ configuration is part of the ONAP parent. See `ONAP
+ Git <https://git.onap.org/oparent/plain/checkstyle/src/main/resources/onap-checkstyle/>`__
+ for details and updates. All settings for checkstyle are
+ already part of the code (POM files).
+
+Configure Eclipse
+-----------------
+
+ .. container:: ulist
+
+ - Set the template for Eclipse code clean up
+
+ .. container:: olist arabic
+
+ #. Eclipse Window Preferences Java Code Style
+ Clean Up → Import…
+
+ #. Select your template file
+ (``ApexCleanUpTemplate.xml``) and apply it
+
+ - Set the Eclipse code templates
+
+ .. container:: olist arabic
+
+ #. Eclipse Window Preferences Java Code Style
+ Code Templates → Import…
+
+ #. Select your templates file
+ (``ApexCodeTemplates.xml``) and apply it
+
+ .. container:: ulist
+
+ - Make sure to set your email address in
+ generated comments by selecting
+ "Comments→Types" in the "Configure generated
+ code and comments:" pane, then change the
+ email address on the @author tag to be your
+ email address
+
+ - Set the Eclipse Formatter profile
+
+ .. container:: olist arabic
+
+ #. Eclipse Window Preferences Java Code Style
+ Formatter → Import…
+
+ #. Select your formatter profile file
+ (``ApexFormatterProfile.xml``) and apply it
+
+ .. container:: paragraph
+
+ The templates mentioned above can be found in
+ ``apex-model/apex-model.build-tools/src/main/resources/eclipse``
+
+Configure JAutodoc (Eclipse)
+----------------------------
+
+ .. container:: paragraph
+
+ Import the settings for JAutodoc:
+
+ .. container:: olist arabic
+
+ #. Eclipse Window Preferences Java JAutodoc → Import
+ All… (at bottom of the JAutodoc preferences window)
+
+ #. Leave all the preferences ticked to import all
+ preferences, browse to the JAutodoc setting file
+ (``ApexJautodocSettings.xml``) and press OK
+
+ #. Set your email address in the package Javadoc template
+
+ .. container:: ulist
+
+ - Press Edit Template… in the Package Javadoc area
+ of the JAutodoc preferences window, and change the
+ email address on the ``@author`` tag to be your
+ email address
+
+ #. Now, apply the JAutodoc settings
+
+ .. container:: paragraph
+
+ The templates mentioned above can be found in
+ ``apex-model/apex-model.build-tools/src/main/resources/eclipse``
+
+Configure Checkstyle (Maven)
+----------------------------
+
+ .. container:: paragraph
+
+ When using a custom style configuration with Checkstyle, the
+ definition of that style must of course be available to
+ Checkstyle. In order not to have to distribute style files
+ for checkstyle into all Maven modules, it is recommended
+ that a special Maven module be built that contains the
+ checkstyle style definition. That module is then used as a
+ dependency in the *POM* for all other modules that wish to
+ use that checkstyle style. For a full explanation see `the
+ explanation of Checkstyle multi-module
+ configuration <https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/multi-module-config.html>`__.
+
+ .. container:: paragraph
+
+ For APEX, the ONAP checkstyle rules do apply. The
+ configuration is part of the ONAP parent. See `ONAP
+ Git <https://git.onap.org/oparent/plain/checkstyle/src/main/resources/onap-checkstyle/>`__
+ for details and updates.
+
+Run Checkstyle (Maven)
+----------------------
+
+ .. container:: paragraph
+
+ Run Checkstyle using Maven on the command line with the
+ command:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ mvn checkstyle:check
+
+ .. container:: paragraph
+
+ On the main APEX project, run a full checkstyle check as:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ mvn checkstyle:checkstyle -DapexAll
+
+Configure Checkstyle (Eclipse, globally)
+----------------------------------------
+
+ .. container:: olist arabic
+
+ #. Set up a module with the Checkstyle style files (see
+ above)
+
+ #. In Eclipse Window Preferences go to Checkstyle
+
+ #. Import the settings for Checkstyle
+
+ .. container:: ulist
+
+ - Press New… to create a new *Global Check
+ Configurations* entry
+
+ - Give the configuration a name such as *Apex
+ Checkstyle Configuration* and select the *External
+ Configuration File* form in the *Type* drop down
+ menu
+
+ - Browse to the Checckstyle setting file
+ (``ApexCheckstyleSettings.xml``) and press OK
+
+ #. Press OK
+
+ .. container:: ulist
+
+ - You may now get an *Unresolved Properties found*
+ dialogue
+
+ - This is because there is a second Checkstyle
+ configuration file required to check file headers
+
+ #. Press Edit Properties… and press Find unresolved
+ properties on the next dialogue window
+
+ #. The plugin will find the ``${checkstyle.header.file}``
+ property is unresolved and will ask should it be added to
+ the properties, click yes
+
+ #. Now, select the row on the dialogue for the
+ ``checkstyle.header.file property`` and click Edit…
+
+ #. Set the value of the ``checkstyle.header.file property``
+ to
+ ``<your-apex-git-location>/apex-model/apex-model.build-tools/src/main/resources/checkstyle/apex_header.txt``
+
+ .. container:: ulist
+
+ - Of course replacing the tag
+ ``<your-apex-git-location>`` with the location of
+ your Apex GIT repository
+
+ #. Press OK, OK, OK to back out to the main Checkstyle
+ properties window
+
+ #. Select the *Apex Checkstyle Configuration* as your
+ default configuration by selecting its line in the
+ *Global Check Configuraitons* list and clicking Set as
+ Default
+
+ #. Press Apply and Close to finish Checkstyle global
+ configuration
+
+ .. container:: paragraph
+
+ The templates mentioned above can be found in
+ ``apex-model/apex-model.build-tools/src/main/resources/eclipse``
+
+2.10. Configure Checkstyle Blueprint
+------------------------------------
+
+ .. container:: paragraph
+
+ As well as being configured globally, Checkstyle must be
+ configured and activated for each project in Eclipse. In
+ order to make this process less tedious, set up the first
+ project you apply Checkstye to as a blueprint project and
+ then use this blueprint for all other projects.
+
+ .. container:: olist arabic
+
+ #. Select the project you want to use as a blueprint
+
+ .. container:: ulist
+
+ - For example, ``apex-model.basic-model`` in ``apex``
+ and enter the project properties by right clicking
+ and selecting **Properties**
+
+ #. Click *Checkstyle* on the properties to get the
+ Checkstyle project configuration window
+
+ #. Click the box *Checkstyle active for this project* and in
+ the *Exclude from checking…* list check the boxes:
+
+ .. container:: ulist checklist
+
+ - *files outside source directories*
+
+ - *derived (generated) files*
+
+ - *files from packages:*
+
+ #. Now, in order to turn off checking on resource
+ directories and on JUnit tests
+
+ .. container:: ulist
+
+ - Select the line *files from packages:* in the
+ *Exclude from checking…* list and click Change…
+
+ #. On the *Filter packages* dialogue
+
+ .. container:: ulist
+
+ - Check all the boxes except the top box, which is
+ the box for *src/main/java*
+
+ - Ensure that the *recursively exclude sub-packages*
+ check box is ticked
+
+ .. container:: ulist checklist
+
+ - *recursively exclude sub-packages*
+
+ - Press OK
+
+ #. Press Apply and Close to apply the changes
+
+Use Eclipse Source Operations
+-----------------------------
+
+ .. container:: paragraph
+
+ Eclipse Source Operations can be carried out on individual
+ files or on all the files in a package but do not recurse
+ into sub-packages. They are available as a menu in Eclipse
+ by selecting a file or package and right clicking on
+ *Source*. Note that running *Clean Up…* with the Apex clean
+ up profile will run *Format* and *Organize Imports*. So if
+ you run a clean up on a file or package, you need not run
+ *Format* or *Organize Imports*.
+
+ .. container:: paragraph
+
+ We recommend you use the following Eclipse Source
+ Operations:
+
+ .. container:: olist arabic
+
+ #. *Format* applies the current format definition to the
+ file or all files in a package
+
+ #. *Organize Imports* sorts the imports on each file in
+ standard order
+
+ #. *Clean Up* runs a number of cleaning operations on each
+ file. The Apex clean up template
+
+ .. container:: ulist
+
+ - Remove ``this`` qualifier for non static field
+ accesses
+
+ - Change non static accesses to static members using
+ declaring type
+
+ - Change indirect accesses to static members to
+ direct accesses (accesses through subtypes)
+
+ - Convert control statement bodies to block
+
+ - Convert ``for`` loops to enhanced ``for`` loops
+
+ - Add final modifier to private fields
+
+ - Add final modifier to local variables
+
+ - Remove unused imports
+
+ - Remove unused private methods
+
+ - Remove unused private constructors
+
+ - Remove unused private types
+
+ - Remove unused private fields
+
+ - Remove unused local variables
+
+ - Add missing ``@Override`` annotations
+
+ - Add missing ``@Override`` annotations to
+ implementations of interface methods
+
+ - Add missing ``@Deprecated`` annotations
+
+ - Add missing serial version ID (generated)
+
+ - Remove unnecessary casts
+
+ - Remove unnecessary ``$NON-NLS$`` tags
+
+ - Organize imports
+
+ - Format source code
+
+ - Remove trailing white spaces on all lines
+
+ - Correct indentation
+
+ - Remove redundant type arguments
+
+ - Add file header (JAutodoc)
+
+Using JAutodoc
+--------------
+
+ .. container:: paragraph
+
+ Similar to Eclipse Source Operations, JAutodoc operations
+ can be carried out on individual files or on all the files
+ in a package but do not recurse into sub-packages. The
+ JAutodoc operations are available by selecting a file or
+ package and right clicking on *JAutodoc*:
+
+ .. container:: olist arabic
+
+ #. To add a ``package-info.java`` file to a package, select
+ the package and right-click Jautodoc Add Package Javadoc
+
+ #. To add headers to files select on a file (or on the
+ package to do all files) and right click JAutodoc Add
+ Header
+
+ #. To add JAutodoc stubs to a files, select on a file (or on
+ the package to do all files) and right click JAutodoc
+ Add Javadoc
+
+Using Checkstyle
+----------------
+
+ .. container:: paragraph
+
+ In order to use Checkstyle, you must configure it per
+ project and then activate it per project. The easiest way to
+ do this is to set up one project as a blueprint and use that
+ blueprint for other projects (see above). Once you have a
+ blueprint project, you can use Checkstyle on other projects
+ as follows
+
+ .. container:: olist arabic
+
+ #. Set up Checkstyle on projects by selecting one or more
+ projects
+
+ .. container:: ulist
+
+ - Right clicking and selecting Checkstyle Configure
+ project(s) from *blueprint…* and then selecting
+ your blueprint project
+
+ - (for example ``apex-model.basic-model``) from the
+ list of projects and pressing OK
+
+ #. Activate Checkstyle on projects by selecting one or more
+ projects
+
+ .. container:: ulist
+
+ - Right clicking and selecting Checkstyle Activate
+ Checkstyle
+
+ - Now Checkstyle warnings will appear on the selected
+ projects if they have warnings
+
+ #. You can disable Checkstyle checking on a file or a
+ package (recursively) by selecting a file or package
+
+ .. container:: ulist
+
+ - Right clicking and selecting Checkstyle Clear
+ Checkstyle violations
+
+ #. You can enable Checkstyle checking on a file or a package
+ (recursively) by selecting a file or package
+
+ .. container:: ulist
+
+ - Right clicking and selecting Checkstyle Check Code
+ with Checkstyle
+
+ #. On individual files, you can apply fixes that clear some
+ Checkstyle warnings
+
+ .. container:: ulist
+
+ - Select the file, right click and select **Apply
+ Checkstyle fixes**
+
+Disable Eclipse Formatting (partially)
+--------------------------------------
+
+ .. container:: paragraph
+
+ Sometimes, the Eclipse code formatting results in correct
+ but untidy indentation, for example when Java Persistence
+ annotations or long sequences of lined-up assignments are
+ formatted. You can disable formatting for sections of code.
+
+ .. container:: olist arabic
+
+ #. Ensure that Off/On Tags are enabled in Eclipse
+
+ #. In Eclipse Window Preferences Java Code Style
+ Formatter window press Edit…
+
+ #. Click on the *Off/On Tags* tab
+
+ #. Ensure that the *Enable Off/On Tags* checkbox is checked
+
+ #. Surround the section of code that you do not want the
+ formatter to act on with comments containing the Off/On
+ tags
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ // @formatter:off
+ // Plugin Parameters
+ private DistributorParameters distributorParameters = new DistributorParameters();
+ private SchemaParameters schemaParameters = new SchemaParameters();
+ private LockManagerParameters lockManagerParameters = new LockManagerParameters();
+ private PersistorParameters persistorParameters = new PersistorParameters();
+ // @formatter:on
+
+Supress Checkstyle (partially)
+------------------------------
+
+ .. container:: paragraph
+
+ Sometimes Checkstyle checks identify code that does not comply
+ with Checkstyle rules. In limited cases Checkstyle rules can be
+ suppressed, for example where it is impossible to design the code
+ in a way that complies with Checkstyle or where the Checkstyle
+ rule is impossible to apply. Checkstyle rules are suppressed as is
+ explained in this `Stackoverflow
+ post <https://stackoverflow.com/questions/4023185/how-to-disable-a-particular-checkstyle-rule-for-a-particular-line-of-code>`__.
+
+ .. container:: paragraph
+
+ The example below illustrates how to suppress a Checkstyle rule
+ that specifies all methods must have seven parameters or less.
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ // CHECKSTYLE:OFF: checkstyle:ParameterNumber
+ public myMethod(final int par1, final int par2, final int par3, final int par4,
+ final int par5, final int par6, final int par7, final int par8) {
+ }
+ // CHECKSTYLE:ON: checkstyle:ParameterNumber
+
+apex-apps.utilities
+^^^^^^^^^^^^^^^^^^^
+
+CLI Example
+-----------
+
+ .. container:: paragraph
+
+ Using the APEX CLI utilities can be done as follows. First,
+ add the dependency of the utility project to your POM file.
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ <dependency>
+ <groupId>org.onap.policy.apex-pdp.tools</groupId>
+ <artifactId>tools-common</artifactId>
+ <version>2.0.0-SNAPSHOT</version>
+ </dependency>
+
+ .. container:: paragraph
+
+ Now, create a new application project, for instance
+ ``MyApp``. In this project, create a new main application
+ class as ``Application.java``. In this class, create a new
+ main method as ``public static void main(String[] args)``.
+
+ .. container:: paragraph
+
+ No use the provided ``CliOptions`` and ``CliParser``.
+ Manually importing means to add the following lines to the
+ start of your application (in Eclipse this import will be
+ done automatically):
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ import org.onap.policy.apex.tools.common.CliOptions;
+ import org.onap.policy.apex.tools.common.CliParser;
+
+.. container:: paragraph
+
+ Now, inside your ``main()`` method, start setting some general
+ application properties. Important are the application name and some
+ description of your application. For instance:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ String appName = "test-app";
+ final String appDescription = "a test app for documenting how to use the CLI utilities";
+
+.. container:: paragraph
+
+ Next, create a new CLI Parser and add a few CLI options from the
+ standard ``CliOptions``. The following example adds options for help,
+ version, and a model file:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ final CliParser cli = new CliParser();
+ cli.addOption(CliOptions.HELP);
+ cli.addOption(CliOptions.VERSION);
+ cli.addOption(CliOptions.MODELFILE);
+
+.. container:: paragraph
+
+ Next, parse the given CLI arguments:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ final CommandLine cmd = cli.parseCli(args);
+
+.. container:: paragraph
+
+ Once the command line is parsed, we can look into the individual
+ options, check if they are set, and then act accordingly. We start
+ with the option for *help*. If the option is present, we print a help
+ screen and return:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ // help is an exit option, print usage and exit
+ if (cmd.hasOption('h') || cmd.hasOption("help")) {
+ final HelpFormatter formatter = new HelpFormatter();
+ LOGGER.info(appName + " v" + cli.getAppVersion() + " - " + appDescription);
+ formatter.printHelp(appName, cli.getOptions());
+ return;
+ }
+
+.. container:: paragraph
+
+ Next, we process the option for *version*. Here, we want to print a
+ version for our application and return. The CLI Parser already
+ provides a method to obtain the correct version for an APEX build, so
+ we use that:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ // version is an exit option, print version and exit
+ if (cmd.hasOption('v') || cmd.hasOption("version")) {
+ LOGGER.info(appName + " " + cli.getAppVersion());
+ return;
+ }
+
+.. container:: paragraph
+
+ Once help and version arguments are processed, we can proceed to look
+ at all other options. We have added an option for a model file, so
+ check this option and test if we can actually load a model file with
+ the given argument. If we can load a model, everything is ok. If we
+ cannot load a model, we print an error and return.
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ String modelFile = cmd.getOptionValue('m');
+ if (modelFile == null) {
+ modelFile = cmd.getOptionValue("model");
+ }
+ if (modelFile == null) {
+ LOGGER.error(appName + ": no model file given, cannot proceed (try -h for help)");
+ return;
+ }
+
+.. container:: paragraph
+
+ With a model file being loadable, we finish parsing command line
+ arguments. We also print some status messages to note that the
+ application now is ready to start:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ LOGGER.info(appName + ": starting");
+ LOGGER.info(" --> model file: " + modelFile);
+
+.. container:: paragraph
+
+ The last action now is to run the actual application. The example
+ below is taken from a version of the ``Model2Cli`` application, which
+ creates a new object and runs it in a ``try`` block, since exceptions
+ might be thrown by the object:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ // your code for the application here
+ // e.g.
+ // try {
+ // Model2Cli app = new Model2Cli(modelFile, !cmd.hasOption("sv"), appName);
+ // app.runApp();
+ // }
+ // catch(ApexException aex) {
+ // LOGGER.error(appName + ": caught APEX exception with message: " + aex.getMessage());
+ // }
+
+.. container:: paragraph
+
+ If this new application is now called with the command line ``-h`` or
+ ``--help`` it will print the following help screen:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ test-app v2.0.0-SNAPSHOT - a test app for documenting how to use the CLI utilities
+ usage: test-app
+ -h,--help prints this help and usage screen
+ -m,--model <MODEL-FILE> set the input policy model file
+ -v,--version prints the application version
+
+.. container:: paragraph
+
+ If this new application is called with the option ``-v`` or
+ ``--version`` it will print its version information as:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ test-app 2.0.0-SNAPSHOT
+
+Autoversioning an Application
+-----------------------------
+
+ .. container:: paragraph
+
+ The APEX utilities project provides means to versioning an
+ application automatically towards the APEX version it is written
+ for. This is realized by generating a file called
+ ``app-version.txt`` that includes the Maven project version. This
+ file is then automatically deployed in the folder ``etc`` of a
+ full APEX distribution. The CLI Parser here provides a mthod to
+ access this version for an application.
+
+ .. container:: paragraph
+
+ First, create a new CLI Parser object, add some options (in the
+ example an option for version, but any options will do), then
+ parse the command line:
+
+ .. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ final CliParser cli = new CliParser();
+ cli.addOption(CliOptions.VERSION);
+ final CommandLine cmd = cli.parseCli(args);
+
+.. container:: paragraph
+
+ Next, we check if the version option was used in the command line and
+ print application name and version if it was used:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ // version is an exit option, print version and exit
+ if (cmd.hasOption('v') || cmd.hasOption("version")) {
+ LOGGER.info("myApp" + " " + cli.getAppVersion());
+ return;
+ }
+
+.. container:: paragraph
+
+ The output will be:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: bash
+
+ myApp 2.0.0-SNAPSHOT
+
+.. container:: paragraph
+
+ The auto-version information comes from the method call
+ ``cli.getAppVersion()`` in line 2 in the example above. The method is
+ defined in the ``CliParser`` class as:
+
+.. container:: listingblock
+
+ .. container:: content
+
+ .. code:: java
+ :number-lines:
+
+ public String getAppVersion() {
+ return new Scanner(CliParser.class.getResourceAsStream("/app-version.txt"), "UTF-8").useDelimiter("\\A").next();
+ }
+
+.. container:: paragraph
+
+ The file ``app-version.txt`` is automatically added to an APEX full
+ distribution, as described above (for details on this see the POM
+ files in the APEX application packaging projects).
+
+.. container::
+ :name: footer
+
+ .. container::
+ :name: footer-text
+
+ 2.0.0-SNAPSHOT
+ Last updated 2018-09-04 16:04:24 IST
Code Review / policy / parent.git / blobdiff