[Skip to content]
TRIEMAX Software
You are here: Home > Products > Jalopy >

### 2.6.10. Header

This section describes the available options to control the handling of headers.

A header is a uniform comment that appears at the very top of a source file and usually displays the company's copyright notice.

Example 2.830. Typical header

    /*
     *                 Sun Public License Notice
     *
     * The contents of this file are subject to the Sun Public License
     * Version 1.0 (the "License"). You may not use this file except in
     * compliance with the License. A copy of the License is available at
     * http://www.sun.com/
     *
     * The Original Code is NetBeans. The Initial Developer of the Original
     * Code is Sun Microsystems, Inc. Portions Copyright 1997-2000 Sun
     * Microsystems, Inc. All Rights Reserved.
     */
    package org.netbeans.editor;

    ...

#### 2.6.10.1. Options

Lets you control the different header options.

Figure 2.87. Header Options settings page

##### 2.6.10.1.1. General

###### Use Header

Enables or disables the header feature. When enabled and no header could be detected, the specified header template will be inserted.

To avoid header duplication, you have to tell Jalopy how to detect existing headers. See Section 2.6.10.1.2, "Detection" below.

###### Override

If you enable this option, the header template will be re-inserted with every run. Any existing header(s) will be removed.

Note that when you specify multiple keys to identify existing headers (see below), all recognized headers will be removed!

This option is only available, if you've enabled the header feature.

Since 1.0

###### Keep tags

When enabled, Jalopy keeps expanded RCS-style tags in existing header comments. An expanded RCS tag looks like `$keyword: data $`.

It is good advise to replace headers upon every formatting run in order to enforce the company's copyright statement under all circumstances. This might cause problems though when the header contains RCS-style tags. Because the current keyword data is lost upon formatting, the SCM thinks the files are different even if the file did not change otherwise. So, after submitting the files show no differences (because the tags have been expanded again by the SCM).

For example, if you have a file with the CVS `$Id$` tag, after checkout the header might look like this

Example 2.831. Header before formatting (keyword data present)

    /* Copyright (c) 2001-2003, Foobar Systems Ltd.
     *
     * $Id: TestCheckin.java,v 1.2 2004/01/12 21:52:18 xf016997 Exp $
     */

But after formatting, the keyword data gets lost when the Keep tags option was disabled

Example 2.832. Header after formatting (keyword data deleted)

    /* Copyright (c) 2001-2003, Foobar Systems Ltd.
     *
     * $Id$
     */

Enabling this option will allow you to keep the existing data and the file will look exactly like in Example 2.831, "Header before formatting (keyword data present)" after formatting.

Please note that this feature works for nested tags, too. If you define RCS tags in your template that contain variable expressions, their values are still kept.

Since 1.0.3

Example 2.833. Header template with nested tags

    //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    // Fossi GmbH Source File: $file.name$
    // Copyright (c) 2003-$date.year$ by Fossi GmbH
    //
    // $Created:    $date$ ($time.long$) by $user.name$ $
    // Last Change: $date$ ($time.long$) by $user.name$
    //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

After the first formatting run, the header could look like this

Example 2.834. Header template after formatting

    //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    // Fossi GmbH Source File: Installer.java
    // Copyright (c) 2003-2004 by Fossi GmbH
    //
    // $Created:    11.05.2004 (09:52:12) by eso $
    // Last Change: 11.05.2004 (09:52:12) by eso
    //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

After the next formatting run, it might look like this

Example 2.835. Header template after further formatting

    //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
    // Fossi GmbH Source File: Installer.java
    // Copyright (c) 2003-2004 by Fossi GmbH
    //
    // $Created:    11.05.2004 (09:52:12) by eso $
    // Last Change: 28.05.2004 (13:04:39) by harold
    //++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++

This option is only available, if you've enabled the header feature.

##### 2.6.10.1.2. Detection

To avoid header duplication, Jalopy needs to know how existing headers can be recognized. Two methods are provided to allow great flexibility.

###### Smart Mode

Lets you specify the number of single-line comments at the top of a file (before the first language keyword, being either `package`, `import`, `class` or `interface`, `@interface` or `enum`) that should be recognized as a header.

Jalopy simply counts the number of single-line comments at the top of a source file and if this number is greater or equal to the specified "Smart Mode" count, all consecutive single-line comments at the top will be assumed to be part of a header.

Example 2.836. Single-line comment header

    //===============================================================
    // file :       Byte.java
    // project:     bsjt-rt
    //
    // last change: date:       $Date$
    //              by:         $Author$
    //              revision:   $Revision$
    //---------------------------------------------------------------
    // copyright:   BSJT Software License (see class documentation)
    //===============================================================

    package com.bsjt.foo;

    import ...

In order to recognize the above single-line comments as a header, the "Smart Mode" count must be no less than '1', but it would be best to set it to '10'.

A number equal to '0' disables "Smart Mode".

###### Keys

The second approach is to specify one or several unique keys that are part of your header. This technique only works with headers that are defined as multi-line comments.

A good key for the header in Example 2.830, "Typical header" above would be "Sun Public License Notice".

Specifying several keys makes it easy to switch between headers. Define both a key for the old header that is to be removed and for your new header that should be inserted. This way, you are sure that even new additions that happens to contain the old header (maybe checked out from some SCM) are treated correctly.

To add, remove or change identify keys, use the corresponding button beneath the keys list.

###### Add...

Lets you add new identify keys. Pressing the button will invoke a new dialog where you can enter the identify key.

Figure 2.88. Add new Identify Key

Enter the identify key in the text field and press the Add button to submit your addition. Press the Cancel button if you want to dismiss the action.

###### Change...

Lets you alter an already defined identify key.

Pressing the button will invoke a new dialog where you can change the currently selected identify key.

Figure 2.89. Change existing Identify Key

Change the identify key and press the Change button to submit your change. Press the Cancel button if you want to dismiss the action.

This button is only available if an item is currently selected in the keys list.

###### Remove

Lets you remove the currently selected key(s) from the list.

This button is only available if an item is currently selected in the keys list.

#### 2.6.10.2. Template

Lets you specify the header template text. Enter the desired text into the text area. You should use either one multi-line comment or several single-line comments. Any leading or trailing white space will be removed upon saving.

Note that if you leave the template text empty, no header template will be inserted during printing but existing headers may still be removed!

Figure 2.90. Header Template settings page

Since Jalopy 1.7, it's also possible to maintain multiple header comments in source files. Please note that if you prefer to separate the different comments with blank lines and don't want to enable the override feature, you need tell Jalopy to keep blank lines between header comments with the "Keep blank lines in headers" option.

You can use variable expressions throughout the template text. See Section 2.3.4, "Usage" for more information about this feature.