docs/apex/APEX-Developer-Guide.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3
   4
   5 APEX Developer Guide
   6 ********************
   7
   8 .. contents::
   9     :depth: 3
  10
  11 Build APEX from Source
  12 ^^^^^^^^^^^^^^^^^^^^^^
  13
  14 Introduction to building APEX
  15 -----------------------------
  16
  17             .. container:: paragraph
  18
  19                APEX is written 100% in Java and uses `Apache
  20                Maven <https://maven.apache.org/>`__ as the build system.
  21                The requirements for building APEX are:
  22
  23             .. container:: ulist
  24
  25                -  An installed Java development kit for Java version 8
  26                   or higher
  27
  28                   .. container:: ulist
  29
  30                      -  To install a Java SDK please follow these
  31                         guidelines `Oracle Java 8
  32                         SDK <https://docs.oracle.com/javase/8/docs/technotes/guides/install/install_overview.html>`__.
  33
  34                -  Maven 3
  35
  36                   .. container:: ulist
  37
  38                      -  To get Maven 3 running please follow the
  39                         guidelines for
  40                         `Download <https://maven.apache.org/download.cgi>`__
  41                         and
  42                         `Install <https://maven.apache.org/install.html>`__,
  43                         and `Run <https://maven.apache.org/run.html>`__
  44                         Maven
  45
  46                -  A clone of the APEX source repositories
  47
  48             .. container:: paragraph
  49
  50                To get a clone of the APEX source repositories, please
  51                see the APEX Installation Guide or the APEX User manual.
  52
  53             .. container:: paragraph
  54
  55                Once all requirements are in place, APEX can be build.
  56                There are several different artifacts one can create
  57                building APEX, most of them defined in their own
  58                *profile*. APEX can also be built in a standard way with
  59                standard tests (``mvn clean install``) or without
  60                standard tests (``mvn clean install -DskipTests``).
  61
  62             .. container:: paragraph
  63
  64                The examples in this document assume that the APEX source
  65                repositories are cloned to:
  66
  67             .. container:: ulist
  68
  69                -  Unix, Cygwin: ``/usr/local/src/apex``
  70
  71                -  Windows: ``C:\dev\apex``
  72
  73                -  Cygwin: ``/cygdrive/c/dev/apex``
  74
  75             .. important::
  76                A Build requires ONAP Nexus
  77                APEX has a dependency to ONAP parent projects. You might need to adjust your Maven M2 settings. The most current
  78                settings can be found in the ONAP oparent repo: `Settings <https://git.onap.org/oparent/plain/settings.xml>`__.
  79
  80             .. important::
  81
  82                A Build needs Space
  83                Building APEX requires approximately 2-3 GB of hard disc space, 1 GB for the actual build with full
  84                distribution and 1-2 GB for the downloaded dependencies
  85
  86             .. important::
  87                A Build requires Internet (for first build to download all dependencies and plugins)
  88                During the build, several (a lot) of Maven dependencies will be downloaded and stored in the configured local Maven
  89                repository. The first standard build (and any first specific build) requires Internet access to download those
  90                dependencies.
  91
  92             .. important::
  93                Building RPM distributions
  94                RPM images are only built if the ``rpm`` package is installed (Unix). To install ``rpm``
  95                run ``sudo apt-get install rpm``, then build APEX.
  96
  97 Standard Build
  98 --------------
  99
 100             .. container:: paragraph
 101
 102                Use Maven to for a standard build without any tests.
 103
 104             +-----------------------------------+------------------------------------+
 105             | Unix, Cygwin                      | Windows                            |
 106             +===================================+====================================+
 107             | ::                                | ::                                 |
 108             |                                   |                                    |
 109             |    >c:                            |    # cd /usr/local/src/apex        |
 110             |    >cd \dev\apex                  |    # mvn clean install -DskipTests |
 111             |    >mvn clean install -DskipTests |                                    |
 112             |                                   |                                    |
 113             +-----------------------------------+------------------------------------+
 114
 115 .. container:: paragraph
 116
 117    The build takes about 6 minutes on a standard development laptop. It
 118    should run through without errors, but with a lot of messages from
 119    the build process.
 120
 121 .. container:: paragraph
 122
 123    When Maven is finished with the build, the final screen should look
 124    similar to this (omitting some ``success`` lines):
 125
 126 .. container:: listingblock
 127
 128    .. code:: bash
 129      :number-lines:
 130
 131      [INFO] tools .............................................. SUCCESS [  0.248 s]
 132      [INFO] tools-common ....................................... SUCCESS [  0.784 s]
 133      [INFO] simple-wsclient .................................... SUCCESS [  3.303 s]
 134      [INFO] model-generator .................................... SUCCESS [  0.644 s]
 135      [INFO] packages ........................................... SUCCESS [  0.336 s]
 136      [INFO] apex-pdp-package-full .............................. SUCCESS [01:10 min]
 137      [INFO] Policy APEX PDP - Docker build 2.0.0-SNAPSHOT ...... SUCCESS [ 10.307 s]
 138      [INFO] ------------------------------------------------------------------------
 139      [INFO] BUILD SUCCESS
 140      [INFO] ------------------------------------------------------------------------
 141      [INFO] Total time: 03:43 min
 142      [INFO] Finished at: 2018-09-03T11:56:01+01:00
 143      [INFO] ------------------------------------------------------------------------
 144
 145 .. container:: paragraph
 146
 147    The build will have created all artifacts required for an APEX
 148    installation. The following example show how to change to the target
 149    directory and how it should look.
 150
 151 +-----------------------------------------------------------------------------------------------------------------------------+
 152 | Unix, Cygwin                                                                                                                |
 153 +=============================================================================================================================+
 154 | .. container::                                                                                                              |
 155 |                                                                                                                             |
 156 |    .. container:: listingblock                                                                                              |
 157 |                                                                                                                             |
 158 |          .. code:: bash                                                                                                     |
 159 |            :number-lines:                                                                                                   |
 160 |                                                                                                                             |
 161 |            # cd packages/apex-pdp-package-full/target                                                                       |
 162 |            # ls -l                                                                                                          |
 163 |            -rwxrwx---+ 1 esvevan Domain Users       772 Sep  3 11:55 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes*      |
 164 |            -rwxrwx---+ 1 esvevan Domain Users 146328082 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT.deb*              |
 165 |            -rwxrwx---+ 1 esvevan Domain Users     15633 Sep  3 11:54 apex-pdp-package-full-2.0.0-SNAPSHOT.jar*              |
 166 |            -rwxrwx---+ 1 esvevan Domain Users 146296819 Sep  3 11:55 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz*   |
 167 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 archive-tmp/                                           |
 168 |            -rwxrwx---+ 1 esvevan Domain Users        89 Sep  3 11:54 checkstyle-cachefile*                                  |
 169 |            -rwxrwx---+ 1 esvevan Domain Users     10621 Sep  3 11:54 checkstyle-checker.xml*                                |
 170 |            -rwxrwx---+ 1 esvevan Domain Users       584 Sep  3 11:54 checkstyle-header.txt*                                 |
 171 |            -rwxrwx---+ 1 esvevan Domain Users        86 Sep  3 11:54 checkstyle-result.xml*                                 |
 172 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 classes/                                               |
 173 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 dependency-maven-plugin-markers/                       |
 174 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 etc/                                                   |
 175 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 examples/                                              |
 176 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:55 install_hierarchy/                                     |
 177 |            drwxrwx---+ 1 esvevan Domain Users         0 Sep  3 11:54 maven-archiver/                                        |
 178 +-----------------------------------------------------------------------------------------------------------------------------+
 179
 180 +-----------------------------------------------------------------------------------------------------------------------------+
 181 | Windows                                                                                                                     |
 182 +=============================================================================================================================+
 183 | .. container::                                                                                                              |
 184 |                                                                                                                             |
 185 |    .. container:: listingblock                                                                                              |
 186 |                                                                                                                             |
 187 |          .. code:: bash                                                                                                     |
 188 |            :number-lines:                                                                                                   |
 189 |                                                                                                                             |
 190 |            >cd packages\apex-pdp-package-full\target                                                                        |
 191 |            >dir                                                                                                             |
 192 |                                                                                                                             |
 193 |            03/09/2018  11:55    <DIR>          .                                                                            |
 194 |            03/09/2018  11:55    <DIR>          ..                                                                           |
 195 |            03/09/2018  11:55       146,296,819 apex-pdp-package-full-2.0.0-SNAPSHOT-tarball.tar.gz                          |
 196 |            03/09/2018  11:55       146,328,082 apex-pdp-package-full-2.0.0-SNAPSHOT.deb                                     |
 197 |            03/09/2018  11:54            15,633 apex-pdp-package-full-2.0.0-SNAPSHOT.jar                                     |
 198 |            03/09/2018  11:55               772 apex-pdp-package-full_2.0.0~SNAPSHOT_all.changes                             |
 199 |            03/09/2018  11:54    <DIR>          archive-tmp                                                                  |
 200 |            03/09/2018  11:54                89 checkstyle-cachefile                                                         |
 201 |            03/09/2018  11:54            10,621 checkstyle-checker.xml                                                       |
 202 |            03/09/2018  11:54               584 checkstyle-header.txt                                                        |
 203 |            03/09/2018  11:54                86 checkstyle-result.xml                                                        |
 204 |            03/09/2018  11:54    <DIR>          classes                                                                      |
 205 |            03/09/2018  11:54    <DIR>          dependency-maven-plugin-markers                                              |
 206 |            03/09/2018  11:54    <DIR>          etc                                                                          |
 207 |            03/09/2018  11:54    <DIR>          examples                                                                     |
 208 |            03/09/2018  11:55    <DIR>          install_hierarchy                                                            |
 209 |            03/09/2018  11:54    <DIR>          maven-archiver                                                               |
 210 |                           8 File(s)    292,652,686 bytes                                                                    |
 211 |                           9 Dir(s)  14,138,720,256 bytes free                                                               |
 212 +-----------------------------------------------------------------------------------------------------------------------------+
 213
 214
 215 Checkstyle with Maven
 216 ---------------------
 217
 218    .. container:: paragraph
 219
 220       The codestyle for all APEX java projects can be checked
 221       automatically. The checks include empty or non-existing Javadocs.
 222       Any checkstyle run should complete without any errors, some
 223       warnings are acceptable.
 224
 225    .. container:: paragraph
 226
 227       To run checkstyle on an APEX Maven project use:
 228
 229    .. container:: listingblock
 230
 231       .. container:: content
 232
 233          .. code:: bash
 234
 235             mvn checkstyle:check
 236
 237    .. container:: paragraph
 238
 239       To run checkstyle on all modules use:
 240
 241    .. container:: listingblock
 242
 243       .. container:: content
 244
 245          .. code:: bash
 246
 247             mvn checkstyle:checkstyle -DapexAll
 248
 249 Build with standard Tests
 250 -------------------------
 251
 252    .. container:: paragraph
 253
 254       Use Maven for a standard build with standard tests.
 255
 256    .. important::
 257       Some tests have specific timing Requirements
 258       Some of the tests have very specific timing requirements. If run on a low-powered build machine, or if the build
 259       machine is on high load, those tests might fail and the whole build might fail as well. If this happens, reduce the load
 260       on your build machine and restart the build.
 261
 262    +-----------------------------------+-----------------------------------+
 263    | Unix, Cygwin                      | Windows                           |
 264    +===================================+===================================+
 265    | .. container::                    | .. container::                    |
 266    |                                   |                                   |
 267    |    .. container:: content         |    .. container:: content         |
 268    |                                   |                                   |
 269    |       .. code:: bash              |       .. code:: bash              |
 270    |         :number-lines:            |         :number-lines:            |
 271    |                                   |                                   |
 272    |         >c:                       |         # cd /usr/local/src/apex  |
 273    |         >cd \dev\apex             |         # mvn clean install       |
 274    |         >mvn clean install        |                                   |
 275    +-----------------------------------+-----------------------------------+
 276
 277
 278 .. container:: paragraph
 279
 280    The build takes about 10 minutes with tests on a standard development
 281    laptop. It should run through without errors, but with a lot of
 282    messages from the build process. If built with tests (i.e. without
 283    ``-DskipTests``), there will be error messages and stack trace prints
 284    from some tests. This is normal, as long as the build finishes
 285    successfully.
 286
 287 Build with all Tests
 288 --------------------
 289
 290    .. container:: paragraph
 291
 292       Use Maven to for a standard build with *all* tests.
 293
 294    .. important::
 295       Some tests have specific timing Requirements.
 296       Some of the tests have very specific timing requirements. If run on a low-powered build machine, or if the build
 297       machine is on high load, those tests might fail and the whole build might fail as well. If this happens, reduce the load
 298       on your build machine and restart the build.
 299
 300    .. important::
 301       Might require specific software.
 302       When running all tests, some modules require specific software installed on the build machine. For instance,
 303       testing the full capabilities of context (with distribution and persistence) will require Hazelcast and Infinispan
 304       installed on the build machine.
 305
 306    +----------------------------------------------+----------------------------------------------+
 307    | Unix, Cygwin                                 | Windows                                      |
 308    +==============================================+==============================================+
 309    | .. container::                               | .. container::                               |
 310    |                                              |                                              |
 311    |    .. container:: content                    |    .. container:: content                    |
 312    |                                              |                                              |
 313    |       .. code:: bash                         |       .. code:: bash                         |
 314    |         :number-lines:                       |         :number-lines:                       |
 315    |                                              |                                              |
 316    |         >c:                                  |         # cd /usr/local/src/apex             |
 317    |         >cd \dev\apex                        |         # mvn clean install -DallTests       |
 318    |         >mvn clean install -DallTests        |                                              |
 319    +----------------------------------------------+----------------------------------------------+
 320
 321 Build with all Components
 322 -------------------------
 323
 324    .. container:: paragraph
 325
 326       A standard APEX build will not build all components. Some parts
 327       are for specific deployments, only. Use Maven for a standard
 328       build with *all* components.
 329
 330    .. important::
 331       Might require specific software.
 332       When building all components, some modules require specific software to be installed on the build machine.
 333
 334    +----------------------------------------------+----------------------------------------------+
 335    | Unix, Cygwin                                 | Windows                                      |
 336    +==============================================+==============================================+
 337    | .. container::                               | .. container::                               |
 338    |                                              |                                              |
 339    |    .. container:: content                    |    .. container:: content                    |
 340    |                                              |                                              |
 341    |       .. code:: bash                         |       .. code:: bash                         |
 342    |         :number-lines:                       |         :number-lines:                       |
 343    |                                              |                                              |
 344    |         >c:                                  |         # cd /usr/local/src/apex             |
 345    |         >cd \dev\apex                        |         # mvn clean install -DapexAll        |
 346    |         >mvn clean install -DapexAll         |                                              |
 347    +----------------------------------------------+----------------------------------------------+
 348
 349
 350 Build the APEX Documentation
 351 ----------------------------
 352
 353    .. container:: paragraph
 354
 355       The APEX Maven build also includes stand-alone documentation,
 356       such as the HowTo documents, the Installation Guide, and the User
 357       Manual. Use Maven to build the APEX Documentation. The Maven
 358       option ``-N`` prevents Maven from going through all APEX modules,
 359       which is not necessary for the documentation. The final documents
 360       will be in ``target/generated-docs`` (Windows:
 361       ``target\generated-docs``). The *HTML* documents are in the
 362       ``html/`` folder, the *PDF* documents are in the ``pdf/`` folder.
 363       Once the documentation is built, copy the *HTML* and *PDF*
 364       documents to a folder of choice
 365
 366    +-------------------------------------------------------+--------------------------------------------------------+
 367    | Unix, Cygwin                                          | Windows                                                |
 368    +=======================================================+========================================================+
 369    | .. container::                                        | .. container::                                         |
 370    |                                                       |                                                        |
 371    |    .. container:: content                             |    .. container:: content                              |
 372    |                                                       |                                                        |
 373    |       .. code:: bash                                  |       .. code:: bash                                   |
 374    |         :number-lines:                                |         :number-lines:                                 |
 375    |                                                       |                                                        |
 376    |         >c:                                           |         # cd /usr/local/src/apex                       |
 377    |         >cd \dev\apex                                 |         # mvn clean generate-resources -N -DapexDocs   |
 378    |         >mvn clean generate-resources -N -DapexDocs   |                                                        |
 379    +-------------------------------------------------------+--------------------------------------------------------+
 380
 381 Build APEX Site
 382 ---------------
 383
 384    .. container:: paragraph
 385
 386       The APEX Maven build comes with full support to build a web site
 387       using Maven Site. Use Maven to build the APEX Site. Stage the APEX
 388       web site. The target folder for the staged site is
 389
 390    .. container:: ulist
 391
 392       -  Unix: ``/usr/local/src/apex/target/ad-site``
 393
 394       -  Windows: ``C:\dev\apex\target\ad-site``
 395
 396       -  Cygwin: ``/cygdrive/c/dev/apex/target/ad-site``
 397
 398    .. container:: paragraph
 399
 400       Once the web site is staged, copy the full site to a folder of
 401       choice or into a web server.
 402
 403    .. important::
 404       Building a Site takes Time.
 405       Building and staging the APEX web site can take very long. The stand-alone documentation will take about 2 minutes. The
 406       sites for all modules and projects and the main APEX site can take between 10-30 minutes depending on your build machine (~10 minutes
 407       without generating source and test-source reports, closer to 30 minutes with all reports).
 408
 409    .. container:: paragraph
 410
 411       Start the build deleting the staging directory that might have
 412       been created by a previous site build. Then go to the APEX
 413       packaging directory.
 414
 415    +--------------------------------+-----------------------------------+----------------------------------+
 416    | Unix                           | Windows                           | Cygwin                           |
 417    +================================+===================================+==================================+
 418    | .. container::                 | .. container::                    | .. container::                   |
 419    |                                |                                   |                                  |
 420    |    .. container:: content      |    .. container:: content         |    .. container:: content        |
 421    |                                |                                   |                                  |
 422    |       .. code:: bash           |       .. code:: bash              |       .. code:: bash             |
 423    |         :number-lines:         |         :number-lines:            |         :number-lines:           |
 424    |                                |                                   |                                  |
 425    |         cd /usr/local/src/apex |         c:                        |         cd /cygdrive/c/dev/apex  |
 426    |         rm -fr target/ad-site  |         cd \dev\apex              |         rm -fr target/ad-site    |
 427    |                                |         rmdir /s/q target\ad-site |                                  |
 428    +--------------------------------+-----------------------------------+----------------------------------+
 429
 430    .. container:: paragraph
 431
 432       the workflow for building a complete site then is as follows:
 433
 434    .. container:: listingblock
 435
 436       .. container:: content
 437
 438          .. code:: bash
 439
 440             mvn clean -DapexAll (1)
 441             mvn install -DskipTests (2)
 442             mvn generate-resources -N -DapexDocs (3)
 443             mvn initialize site:attach-descriptor site site:stage -DapexSite (4)
 444
 445    .. container:: olist arabic
 446
 447       #. First clean all modules to remove any site artifacts, use the
 448          *apexXtext* profile to make sure these modules are processed as
 449          well
 450
 451       #. Next run a simple install without tests
 452
 453       #. Now generate the APEX stand-alone documentation, they are in
 454          the local package only so we can use the *-N* switch
 455
 456       #. Last build the actual sites and stage (copy to the staging
 457          directory) with the profile *apexSite* (do not forget the
 458          initialize goal, otherwise the staging directory will not be
 459          correctly set and sites are staged in every model in a
 460          directory called ``docs``).
 461
 462    .. container:: paragraph
 463
 464       If you want to build the site for a particular project for
 465       testing, the Maven command is simpler. Since only the main project
 466       has APEX documentation (stand-alone), you can use Maven as follow.
 467
 468    .. container:: listingblock
 469
 470       .. container:: content
 471
 472          .. code:: bash
 473
 474             mvn clean site -DapexSite
 475
 476    .. container:: paragraph
 477
 478       If you want to stage the tested site, then use
 479
 480    .. container:: listingblock
 481
 482       .. container:: content
 483
 484          .. code:: bash
 485
 486             mvn clean initialize site:attach-descriptor site site:stage -DapexSite
 487
 488 APEX Codestyle
 489 ^^^^^^^^^^^^^^
 490
 491 Introduction: APEX Codestyle
 492 ----------------------------
 493
 494          .. container:: paragraph
 495
 496             This page describes how to apply a code style to the APEX
 497             Java projects. The provided code templates are guidelines
 498             and are provided for references and as examples. We will not
 499             engage in "holy war" on style for coding. As long as the
 500             style of a particular block of code is understandable,
 501             consistent, and readable, please feel free to adapt or
 502             modify these guides or use other guides as you see fit.
 503
 504          .. container:: paragraph
 505
 506             The JAutoDoc and Checkstyle Eclipse Plugins and tools are
 507             useful and remove a lot of the tedium from code
 508             documentation. Use them to check your code and please fix
 509             any issues they identify with your code.
 510
 511          .. container:: paragraph
 512
 513             Since APEX is part of ONAP, the general ONAP rules and
 514             guideliness for development do apply. Please see `ONAP
 515             Wiki <https://wiki.onap.org/display/DW/Developing+ONAP>`__
 516             for details.
 517
 518 Java coding Rules
 519 -----------------
 520
 521          .. container:: ulist
 522
 523             -  APEX is (in large parts) a platform (or middleware), so
 524                `Software Design
 525                Patterns <https://en.wikipedia.org/wiki/Software_design_pattern>`__
 526                are a good thing
 527
 528             -  The `Solid
 529                Principles <https://en.wikipedia.org/wiki/SOLID_(object-oriented_design)>`__
 530                apply
 531
 532             -  Avoid class fields scoped as ``protected``
 533
 534                .. container:: ulist
 535
 536                   -  They break a lot of good design rules, e.g. most
 537                      SOLID rules
 538
 539                   -  For a discussion see this `Stackoverflow
 540                      Question <https://softwareengineering.stackexchange.com/questions/162643/why-is-clean-code-suggesting-avoiding-protected-variables>`__
 541
 542             -  If you absolutely need ``protected`` class fields they
 543                should be ``final``
 544
 545             -  Avoid ``default`` scope for class fields and methods
 546
 547                .. container:: ulist
 548
 549                   -  For fields: use ``public`` or ``private`` (see also
 550                      above)
 551
 552                   -  For methods: use ``public`` for general use,
 553                      ``protected`` for specialization using inheritance
 554                      (ideally ``final``), ``private`` for everything
 555                      else
 556
 557             -  Method parameters that are not changed in the method
 558                should be marked ``final``
 559
 560             -  Every package must have a ``package-info.java`` file with
 561                an appropriate description, minimum a descriptive one
 562                liner
 563
 564             -  Every class must have
 565
 566                .. container:: ulist
 567
 568                   -  The common header (copyright, file, date)
 569
 570                   -  Javadoc header for the class with description of
 571                      the class and author
 572
 573                   -  Javadoc for *all public\_* fields
 574
 575                   -  If possible, Javadoc for *private* fields, at least
 576                      some documentation for private fields
 577
 578                   -  Javadoc for *all* methods
 579
 580             -  All projects must build with all tests on Unix, Windows,
 581                *and* Cygwin
 582
 583                .. container:: ulist
 584
 585                   -  Support all line endings in files, e.g. ``\n`` and
 586                      ``\r\n``
 587
 588                   -  Be aware of potential differences in exception
 589                      messages, if testing against a message
 590
 591                   -  Support all types of paths: Unix with ``/``,
 592                      Windows with an optinal drive ``C:\`` and ``\``,
 593                      Cygwin with mixed paths
 594
 595 Eclipse Plugin: JAutodoc
 596 ------------------------
 597
 598          .. container:: paragraph
 599
 600             This plugin is a helper plugin for writing Javadoc. It will
 601             automatically create standard headers on files, create
 602             package-info.java files and will put in remarkably good stub
 603             Javadoc comments in your code, using class names and method
 604             names as hints.
 605
 606          .. container:: paragraph
 607
 608             Available from the Eclipse Marketplace. In Eclipse
 609             Help→Eclipse Marketplace… and type ``JAutodoc``. Select
 610             JAutodoc when the search returns and install it.
 611
 612          .. container:: paragraph
 613
 614             You must configure JAutoDoc in order to get the most out of
 615             it. Ideally JAutoDoc should be configured with templates
 616             that cooperate with the inbuilt Eclipse Code Formatter for
 617             best results.
 618
 619 Eclipse Plugin: Checkstyle
 620 --------------------------
 621
 622          .. container:: paragraph
 623
 624             This plugin integrates
 625             `Checkstyle <http://checkstyle.sourceforge.net/>`__ into
 626             Eclipse. It will check your code and flag any checkstyle
 627             issues as warnings in the code.
 628
 629          .. container:: paragraph
 630
 631             Available from the Eclipse Marketplace. In Eclipse
 632             Help→Eclipse Marketplace… and type "Checkstyle". Select
 633             "Checkstyle Plug-in" when the search returns and install it.
 634             Note that "Checkstyle Plug-in" may not be the first result
 635             in the list of items returned.
 636
 637          .. container:: paragraph
 638
 639             For APEX, the ONAP checkstyle rules do apply. The
 640             configuration is part of the ONAP parent. See `ONAP
 641             Git <https://git.onap.org/oparent/plain/checkstyle/src/main/resources/onap-checkstyle/>`__
 642             for details and updates. All settings for checkstyle are
 643             already part of the code (POM files).
 644
 645 Configure Eclipse
 646 -----------------
 647
 648          .. container:: ulist
 649
 650             -  Set the template for Eclipse code clean up
 651
 652                .. container:: olist arabic
 653
 654                   #. Eclipse  Window  Preferences  Java  Code Style
 655                      Clean Up → Import…
 656
 657                   #. Select your template file
 658                      (``ApexCleanUpTemplate.xml``) and apply it
 659
 660             -  Set the Eclipse code templates
 661
 662                .. container:: olist arabic
 663
 664                   #. Eclipse  Window  Preferences  Java  Code Style
 665                      Code Templates → Import…
 666
 667                   #. Select your templates file
 668                      (``ApexCodeTemplates.xml``) and apply it
 669
 670                      .. container:: ulist
 671
 672                         -  Make sure to set your email address in
 673                            generated comments by selecting
 674                            "Comments→Types" in the "Configure generated
 675                            code and comments:" pane, then change the
 676                            email address on the @author tag to be your
 677                            email address
 678
 679             -  Set the Eclipse Formatter profile
 680
 681                .. container:: olist arabic
 682
 683                   #. Eclipse  Window  Preferences  Java  Code Style
 684                      Formatter → Import…
 685
 686                   #. Select your formatter profile file
 687                      (``ApexFormatterProfile.xml``) and apply it
 688
 689          .. container:: paragraph
 690
 691             The templates mentioned above can be found in
 692             ``apex-model/apex-model.build-tools/src/main/resources/eclipse``
 693
 694 Configure JAutodoc (Eclipse)
 695 ----------------------------
 696
 697          .. container:: paragraph
 698
 699             Import the settings for JAutodoc:
 700
 701          .. container:: olist arabic
 702
 703             #. Eclipse  Window  Preferences  Java  JAutodoc → Import
 704                All… (at bottom of the JAutodoc preferences window)
 705
 706             #. Leave all the preferences ticked to import all
 707                preferences, browse to the JAutodoc setting file
 708                (``ApexJautodocSettings.xml``) and press OK
 709
 710             #. Set your email address in the package Javadoc template
 711
 712                .. container:: ulist
 713
 714                   -  Press Edit Template… in the Package Javadoc area
 715                      of the JAutodoc preferences window, and change the
 716                      email address on the ``@author`` tag to be your
 717                      email address
 718
 719             #. Now, apply the JAutodoc settings
 720
 721          .. container:: paragraph
 722
 723             The templates mentioned above can be found in
 724             ``apex-model/apex-model.build-tools/src/main/resources/eclipse``
 725
 726 Configure Checkstyle (Maven)
 727 ----------------------------
 728
 729          .. container:: paragraph
 730
 731             When using a custom style configuration with Checkstyle, the
 732             definition of that style must of course be available to
 733             Checkstyle. In order not to have to distribute style files
 734             for checkstyle into all Maven modules, it is recommended
 735             that a special Maven module be built that contains the
 736             checkstyle style definition. That module is then used as a
 737             dependency in the *POM* for all other modules that wish to
 738             use that checkstyle style. For a full explanation see `the
 739             explanation of Checkstyle multi-module
 740             configuration <https://maven.apache.org/plugins/maven-checkstyle-plugin/examples/multi-module-config.html>`__.
 741
 742          .. container:: paragraph
 743
 744             For APEX, the ONAP checkstyle rules do apply. The
 745             configuration is part of the ONAP parent. See `ONAP
 746             Git <https://git.onap.org/oparent/plain/checkstyle/src/main/resources/onap-checkstyle/>`__
 747             for details and updates.
 748
 749 Run Checkstyle (Maven)
 750 ----------------------
 751
 752          .. container:: paragraph
 753
 754             Run Checkstyle using Maven on the command line with the
 755             command:
 756
 757          .. container:: listingblock
 758
 759             .. container:: content
 760
 761                .. code:: bash
 762
 763                   mvn checkstyle:check
 764
 765          .. container:: paragraph
 766
 767             On the main APEX project, run a full checkstyle check as:
 768
 769          .. container:: listingblock
 770
 771             .. container:: content
 772
 773                .. code:: bash
 774
 775                   mvn checkstyle:checkstyle -DapexAll
 776
 777 Configure Checkstyle (Eclipse, globally)
 778 ----------------------------------------
 779
 780          .. container:: olist arabic
 781
 782             #. Set up a module with the Checkstyle style files (see
 783                above)
 784
 785             #. In Eclipse  Window  Preferences go to Checkstyle
 786
 787             #. Import the settings for Checkstyle
 788
 789                .. container:: ulist
 790
 791                   -  Press New… to create a new *Global Check
 792                      Configurations* entry
 793
 794                   -  Give the configuration a name such as *Apex
 795                      Checkstyle Configuration* and select the *External
 796                      Configuration File* form in the *Type* drop down
 797                      menu
 798
 799                   -  Browse to the Checckstyle setting file
 800                      (``ApexCheckstyleSettings.xml``) and press OK
 801
 802             #. Press OK
 803
 804                .. container:: ulist
 805
 806                   -  You may now get an *Unresolved Properties found*
 807                      dialogue
 808
 809                   -  This is because there is a second Checkstyle
 810                      configuration file required to check file headers
 811
 812             #. Press Edit Properties… and press Find unresolved
 813                properties on the next dialogue window
 814
 815             #. The plugin will find the ``${checkstyle.header.file}``
 816                property is unresolved and will ask should it be added to
 817                the properties, click yes
 818
 819             #. Now, select the row on the dialogue for the
 820                ``checkstyle.header.file property`` and click Edit…
 821
 822             #. Set the value of the ``checkstyle.header.file property``
 823                to
 824                ``<your-apex-git-location>/apex-model/apex-model.build-tools/src/main/resources/checkstyle/apex_header.txt``
 825
 826                .. container:: ulist
 827
 828                   -  Of course replacing the tag
 829                      ``<your-apex-git-location>`` with the location of
 830                      your Apex GIT repository
 831
 832             #. Press OK, OK, OK to back out to the main Checkstyle
 833                properties window
 834
 835             #. Select the *Apex Checkstyle Configuration* as your
 836                default configuration by selecting its line in the
 837                *Global Check Configuraitons* list and clicking Set as
 838                Default
 839
 840             #. Press Apply and Close to finish Checkstyle global
 841                configuration
 842
 843          .. container:: paragraph
 844
 845             The templates mentioned above can be found in
 846             ``apex-model/apex-model.build-tools/src/main/resources/eclipse``
 847
 848 2.10. Configure Checkstyle Blueprint
 849 ------------------------------------
 850
 851          .. container:: paragraph
 852
 853             As well as being configured globally, Checkstyle must be
 854             configured and activated for each project in Eclipse. In
 855             order to make this process less tedious, set up the first
 856             project you apply Checkstye to as a blueprint project and
 857             then use this blueprint for all other projects.
 858
 859          .. container:: olist arabic
 860
 861             #. Select the project you want to use as a blueprint
 862
 863                .. container:: ulist
 864
 865                   -  For example, ``apex-model.basic-model`` in ``apex``
 866                      and enter the project properties by right clicking
 867                      and selecting **Properties**
 868
 869             #. Click *Checkstyle* on the properties to get the
 870                Checkstyle project configuration window
 871
 872             #. Click the box *Checkstyle active for this project* and in
 873                the *Exclude from checking…* list check the boxes:
 874
 875                .. container:: ulist checklist
 876
 877                   -   *files outside source directories*
 878
 879                   -   *derived (generated) files*
 880
 881                   -   *files from packages:*
 882
 883             #. Now, in order to turn off checking on resource
 884                directories and on JUnit tests
 885
 886                .. container:: ulist
 887
 888                   -  Select the line *files from packages:* in the
 889                      *Exclude from checking…* list and click Change…
 890
 891             #. On the *Filter packages* dialogue
 892
 893                .. container:: ulist
 894
 895                   -  Check all the boxes except the top box, which is
 896                      the box for *src/main/java*
 897
 898                   -  Ensure that the *recursively exclude sub-packages*
 899                      check box is ticked
 900
 901                      .. container:: ulist checklist
 902
 903                         -   *recursively exclude sub-packages*
 904
 905                   -  Press OK
 906
 907             #. Press Apply and Close to apply the changes
 908
 909 Use Eclipse Source Operations
 910 -----------------------------
 911
 912          .. container:: paragraph
 913
 914             Eclipse Source Operations can be carried out on individual
 915             files or on all the files in a package but do not recurse
 916             into sub-packages. They are available as a menu in Eclipse
 917             by selecting a file or package and right clicking on
 918             *Source*. Note that running *Clean Up…* with the Apex clean
 919             up profile will run *Format* and *Organize Imports*. So if
 920             you run a clean up on a file or package, you need not run
 921             *Format* or *Organize Imports*.
 922
 923          .. container:: paragraph
 924
 925             We recommend you use the following Eclipse Source
 926             Operations:
 927
 928          .. container:: olist arabic
 929
 930             #. *Format* applies the current format definition to the
 931                file or all files in a package
 932
 933             #. *Organize Imports* sorts the imports on each file in
 934                standard order
 935
 936             #. *Clean Up* runs a number of cleaning operations on each
 937                file. The Apex clean up template
 938
 939                .. container:: ulist
 940
 941                   -  Remove ``this`` qualifier for non static field
 942                      accesses
 943
 944                   -  Change non static accesses to static members using
 945                      declaring type
 946
 947                   -  Change indirect accesses to static members to
 948                      direct accesses (accesses through subtypes)
 949
 950                   -  Convert control statement bodies to block
 951
 952                   -  Convert ``for`` loops to enhanced ``for`` loops
 953
 954                   -  Add final modifier to private fields
 955
 956                   -  Add final modifier to local variables
 957
 958                   -  Remove unused imports
 959
 960                   -  Remove unused private methods
 961
 962                   -  Remove unused private constructors
 963
 964                   -  Remove unused private types
 965
 966                   -  Remove unused private fields
 967
 968                   -  Remove unused local variables
 969
 970                   -  Add missing ``@Override`` annotations
 971
 972                   -  Add missing ``@Override`` annotations to
 973                      implementations of interface methods
 974
 975                   -  Add missing ``@Deprecated`` annotations
 976
 977                   -  Add missing serial version ID (generated)
 978
 979                   -  Remove unnecessary casts
 980
 981                   -  Remove unnecessary ``$NON-NLS$`` tags
 982
 983                   -  Organize imports
 984
 985                   -  Format source code
 986
 987                   -  Remove trailing white spaces on all lines
 988
 989                   -  Correct indentation
 990
 991                   -  Remove redundant type arguments
 992
 993                   -  Add file header (JAutodoc)
 994
 995 Using JAutodoc
 996 --------------
 997
 998          .. container:: paragraph
 999
1000             Similar to Eclipse Source Operations, JAutodoc operations
1001             can be carried out on individual files or on all the files
1002             in a package but do not recurse into sub-packages. The
1003             JAutodoc operations are available by selecting a file or
1004             package and right clicking on *JAutodoc*:
1005
1006          .. container:: olist arabic
1007
1008             #. To add a ``package-info.java`` file to a package, select
1009                the package and right-click Jautodoc  Add Package Javadoc
1010
1011             #. To add headers to files select on a file (or on the
1012                package to do all files) and right click JAutodoc  Add
1013                Header
1014
1015             #. To add JAutodoc stubs to files, select on a file (or on
1016                the package to do all files) and right click JAutodoc
1017                Add Javadoc
1018
1019 Using Checkstyle
1020 ----------------
1021
1022          .. container:: paragraph
1023
1024             In order to use Checkstyle, you must configure it per
1025             project and then activate it per project. The easiest way to
1026             do this is to set up one project as a blueprint and use that
1027             blueprint for other projects (see above). Once you have a
1028             blueprint project, you can use Checkstyle on other projects
1029             as follows
1030
1031          .. container:: olist arabic
1032
1033             #. Set up Checkstyle on projects by selecting one or more
1034                projects
1035
1036                .. container:: ulist
1037
1038                   -  Right clicking and selecting Checkstyle  Configure
1039                      project(s) from *blueprint…* and then selecting
1040                      your blueprint project
1041
1042                   -  (for example ``apex-model.basic-model``) from the
1043                      list of projects and pressing OK
1044
1045             #. Activate Checkstyle on projects by selecting one or more
1046                projects
1047
1048                .. container:: ulist
1049
1050                   -  Right clicking and selecting Checkstyle  Activate
1051                      Checkstyle
1052
1053                   -  Now Checkstyle warnings will appear on the selected
1054                      projects if they have warnings
1055
1056             #. You can disable Checkstyle checking on a file or a
1057                package (recursively) by selecting a file or package
1058
1059                .. container:: ulist
1060
1061                   -  Right clicking and selecting Checkstyle  Clear
1062                      Checkstyle violations
1063
1064             #. You can enable Checkstyle checking on a file or a package
1065                (recursively) by selecting a file or package
1066
1067                .. container:: ulist
1068
1069                   -  Right clicking and selecting Checkstyle  Check Code
1070                      with Checkstyle
1071
1072             #. On individual files, you can apply fixes that clear some
1073                Checkstyle warnings
1074
1075                .. container:: ulist
1076
1077                   -  Select the file, right click and select **Apply
1078                      Checkstyle fixes**
1079
1080 Disable Eclipse Formatting (partially)
1081 --------------------------------------
1082
1083          .. container:: paragraph
1084
1085             Sometimes, the Eclipse code formatting results in correct
1086             but untidy indentation, for example when Java Persistence
1087             annotations or long sequences of lined-up assignments are
1088             formatted. You can disable formatting for sections of code.
1089
1090          .. container:: olist arabic
1091
1092             #. Ensure that Off/On Tags are enabled in Eclipse
1093
1094             #. In Eclipse  Window  Preferences  Java  Code Style
1095                Formatter window press Edit…
1096
1097             #. Click on the *Off/On Tags* tab
1098
1099             #. Ensure that the *Enable Off/On Tags* checkbox is checked
1100
1101             #. Surround the section of code that you do not want the
1102                formatter to act on with comments containing the Off/On
1103                tags
1104
1105          .. container:: listingblock
1106
1107             .. container:: content
1108
1109                .. code:: java
1110                  :number-lines:
1111
1112                  // @formatter:off
1113                  // Plugin Parameters
1114                  private DistributorParameters distributorParameters = new DistributorParameters();
1115                  private SchemaParameters      schemaParameters      = new SchemaParameters();
1116                  private LockManagerParameters lockManagerParameters = new LockManagerParameters();
1117                  private PersistorParameters   persistorParameters   = new PersistorParameters();
1118                  // @formatter:on
1119
1120 Supress Checkstyle (partially)
1121 ------------------------------
1122
1123    .. container:: paragraph
1124
1125       Sometimes Checkstyle checks identify code that does not comply
1126       with Checkstyle rules. In limited cases Checkstyle rules can be
1127       suppressed, for example where it is impossible to design the code
1128       in a way that complies with Checkstyle or where the Checkstyle
1129       rule is impossible to apply. Checkstyle rules are suppressed as is
1130       explained in this `Stackoverflow
1131       post <https://stackoverflow.com/questions/4023185/how-to-disable-a-particular-checkstyle-rule-for-a-particular-line-of-code>`__.
1132
1133    .. container:: paragraph
1134
1135       The example below illustrates how to suppress a Checkstyle rule
1136       that specifies all methods must have seven parameters or less.
1137
1138    .. container:: listingblock
1139
1140       .. container:: content
1141
1142          .. code:: java
1143             :number-lines:
1144
1145             // CHECKSTYLE:OFF: checkstyle:ParameterNumber
1146             public myMethod(final int par1, final int par2, final int par3, final int par4,
1147               final int par5, final int par6, final int par7, final int par8) {
1148             }
1149             // CHECKSTYLE:ON: checkstyle:ParameterNumber
1150
1151 apex-apps.utilities
1152 ^^^^^^^^^^^^^^^^^^^
1153
1154 CLI Example
1155 -----------
1156
1157          .. container:: paragraph
1158
1159             Using the APEX CLI utilities can be done as follows. First,
1160             add the dependency of the utility project to your POM file.
1161
1162          .. container:: listingblock
1163
1164             .. container:: content
1165
1166                .. code:: bash
1167
1168                   <dependency>
1169                     <groupId>org.onap.policy.apex-pdp.tools</groupId>
1170                     <artifactId>tools-common</artifactId>
1171                     <version>2.0.0-SNAPSHOT</version>
1172                   </dependency>
1173
1174          .. container:: paragraph
1175
1176             Now, create a new application project, for instance
1177             ``MyApp``. In this project, create a new main application
1178             class as ``Application.java``. In this class, create a new
1179             main method as ``public static void main(String[] args)``.
1180
1181          .. container:: paragraph
1182
1183             Now use the provided ``CliOptions`` and ``CliParser``.
1184             Manually importing means to add the following lines to the
1185             start of your application (in Eclipse this import will be
1186             done automatically):
1187
1188          .. container:: listingblock
1189
1190             .. container:: content
1191
1192                .. code:: java
1193                   :number-lines:
1194
1195                   import org.onap.policy.apex.tools.common.CliOptions;
1196                   import org.onap.policy.apex.tools.common.CliParser;
1197
1198 .. container:: paragraph
1199
1200    Now, inside your ``main()`` method, start setting some general
1201    application properties. Important are the application name and some
1202    description of your application. For instance:
1203
1204 .. container:: listingblock
1205
1206    .. container:: content
1207
1208       .. code:: java
1209          :number-lines:
1210
1211          String appName = "test-app";
1212          final String appDescription = "a test app for documenting how to use the CLI utilities";
1213
1214 .. container:: paragraph
1215
1216    Next, create a new CLI Parser and add a few CLI options from the
1217    standard ``CliOptions``. The following example adds options for help,
1218    version, and a model file:
1219
1220 .. container:: listingblock
1221
1222    .. container:: content
1223
1224       .. code:: java
1225          :number-lines:
1226
1227          final CliParser cli = new CliParser();
1228          cli.addOption(CliOptions.HELP);
1229          cli.addOption(CliOptions.VERSION);
1230          cli.addOption(CliOptions.MODELFILE);
1231
1232 .. container:: paragraph
1233
1234    Next, parse the given CLI arguments:
1235
1236 .. container:: listingblock
1237
1238    .. container:: content
1239
1240       .. code:: java
1241          :number-lines:
1242
1243          final CommandLine cmd = cli.parseCli(args);
1244
1245 .. container:: paragraph
1246
1247    Once the command line is parsed, we can look into the individual
1248    options, check if they are set, and then act accordingly. We start
1249    with the option for *help*. If the option is present, we print a help
1250    screen and return:
1251
1252 .. container:: listingblock
1253
1254    .. container:: content
1255
1256       .. code:: java
1257          :number-lines:
1258
1259          // help is an exit option, print usage and exit
1260          if (cmd.hasOption('h') || cmd.hasOption("help")) {
1261              final HelpFormatter formatter = new HelpFormatter();
1262              LOGGER.info(appName + " v" + cli.getAppVersion() + " - " + appDescription);
1263              formatter.printHelp(appName, cli.getOptions());
1264              return;
1265          }
1266
1267 .. container:: paragraph
1268
1269    Next, we process the option for *version*. Here, we want to print a
1270    version for our application and return. The CLI Parser already
1271    provides a method to obtain the correct version for an APEX build, so
1272    we use that:
1273
1274 .. container:: listingblock
1275
1276    .. container:: content
1277
1278       .. code:: java
1279          :number-lines:
1280
1281          // version is an exit option, print version and exit
1282          if (cmd.hasOption('v') || cmd.hasOption("version")) {
1283              LOGGER.info(appName + " " + cli.getAppVersion());
1284              return;
1285          }
1286
1287 .. container:: paragraph
1288
1289    Once help and version arguments are processed, we can proceed to look
1290    at all other options. We have added an option for a model file, so
1291    check this option and test if we can actually load a model file with
1292    the given argument. If we can load a model, everything is ok. If we
1293    cannot load a model, we print an error and return.
1294
1295 .. container:: listingblock
1296
1297    .. container:: content
1298
1299       .. code:: java
1300          :number-lines:
1301
1302          String modelFile = cmd.getOptionValue('m');
1303          if (modelFile == null) {
1304              modelFile = cmd.getOptionValue("model");
1305          }
1306          if (modelFile == null) {
1307              LOGGER.error(appName + ": no model file given, cannot proceed (try -h for help)");
1308              return;
1309          }
1310
1311 .. container:: paragraph
1312
1313    With a model file being loadable, we finish parsing command line
1314    arguments. We also print some status messages to note that the
1315    application now is ready to start:
1316
1317 .. container:: listingblock
1318
1319    .. container:: content
1320
1321       .. code:: java
1322          :number-lines:
1323
1324          LOGGER.info(appName + ": starting");
1325          LOGGER.info(" --> model file: " + modelFile);
1326
1327 .. container:: paragraph
1328
1329    The last action now is to run the actual application. The example
1330    below is taken from a version of the ``Model2Cli`` application, which
1331    creates a new object and runs it in a ``try`` block, since exceptions
1332    might be thrown by the object:
1333
1334 .. container:: listingblock
1335
1336    .. container:: content
1337
1338       .. code:: java
1339          :number-lines:
1340
1341          // your code for the application here
1342          // e.g.
1343          // try {
1344          // Model2Cli app = new Model2Cli(modelFile, !cmd.hasOption("sv"), appName);
1345          // app.runApp();
1346          // }
1347          // catch(ApexException aex) {
1348          // LOGGER.error(appName + ": caught APEX exception with message: " + aex.getMessage());
1349          // }
1350
1351 .. container:: paragraph
1352
1353    If this new application is now called with the command line ``-h`` or
1354    ``--help`` it will print the following help screen:
1355
1356 .. container:: listingblock
1357
1358    .. container:: content
1359
1360       .. code:: bash
1361
1362          test-app v2.0.0-SNAPSHOT - a test app for documenting how to use the CLI utilities
1363          usage: test-app
1364           -h,--help                 prints this help and usage screen
1365           -m,--model <MODEL-FILE>   set the input policy model file
1366           -v,--version              prints the application version
1367
1368 .. container:: paragraph
1369
1370    If this new application is called with the option ``-v`` or
1371    ``--version`` it will print its version information as:
1372
1373 .. container:: listingblock
1374
1375    .. container:: content
1376
1377       .. code:: bash
1378
1379          test-app 2.0.0-SNAPSHOT
1380
1381 Autoversioning an Application
1382 -----------------------------
1383
1384    .. container:: paragraph
1385
1386       The APEX utilities project provides a means to version an
1387       application automatically towards the APEX version for which it is
1388       written. This is realized by generating a file called
1389       ``app-version.txt`` that includes the Maven project version. This
1390       file is then automatically deployed in the folder ``etc`` of a
1391       full APEX distribution. The CLI Parser here provides a method to
1392       access this version for an application.
1393
1394    .. container:: paragraph
1395
1396       First, create a new CLI Parser object, add some options (in the
1397       example an option for version, but any options will do), then
1398       parse the command line:
1399
1400    .. container:: listingblock
1401
1402       .. container:: content
1403
1404          .. code:: java
1405             :number-lines:
1406
1407             final CliParser cli = new CliParser();
1408             cli.addOption(CliOptions.VERSION);
1409             final CommandLine cmd = cli.parseCli(args);
1410
1411 .. container:: paragraph
1412
1413    Next, we check if the version option was used in the command line and
1414    print application name and version if it was used:
1415
1416 .. container:: listingblock
1417
1418    .. container:: content
1419
1420       .. code:: java
1421          :number-lines:
1422
1423          // version is an exit option, print version and exit
1424          if (cmd.hasOption('v') || cmd.hasOption("version")) {
1425              LOGGER.info("myApp" + " " + cli.getAppVersion());
1426              return;
1427          }
1428
1429 .. container:: paragraph
1430
1431    The output will be:
1432
1433 .. container:: listingblock
1434
1435    .. container:: content
1436
1437       .. code:: bash
1438
1439          myApp 2.0.0-SNAPSHOT
1440
1441 .. container:: paragraph
1442
1443    The auto-version information comes from the method call
1444    ``cli.getAppVersion()`` in line 2 in the example above. The method is
1445    defined in the ``CliParser`` class as:
1446
1447 .. container:: listingblock
1448
1449    .. container:: content
1450
1451       .. code:: java
1452          :number-lines:
1453
1454          public String getAppVersion() {
1455              return new Scanner(CliParser.class.getResourceAsStream("/app-version.txt"), "UTF-8").useDelimiter("\\A").next();
1456          }
1457
1458 .. container:: paragraph
1459
1460    The file ``app-version.txt`` is automatically added to an APEX full
1461    distribution, as described above (for details on this see the POM
1462    files in the APEX application packaging projects).
1463
1464 .. container::
1465    :name: footer
1466
1467    .. container::
1468       :name: footer-text
1469
1470       2.0.0-SNAPSHOT
1471       Last updated 2018-09-04 16:04:24 IST