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.859. Typical header before package statement

/*
 *                 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;

...

Options

Lets you control the different header options.

Figure 2.88. Header Options settings page

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 the section called “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.860. 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.861. 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.860, “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.862. 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.863. 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.864. 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, when the header feature has been enabled.

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, 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.865. 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≵.

Identify 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. To add, remove or change identify keys, use the corresponding button beneath the keys list.

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 happen to contain the old header (maybe checked out from some SCM) are treated correctly. A good key for the header in Example 2.859, “Typical header before package statement” above would be ≴Sun Public License Notice≵.

Add...

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

Figure 2.89. 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. Please note that the Add button is only available if the text field is not empty!

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. The button is only available if an item is currently selected in the keys list.

Figure 2.90. 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. Please note that the Change button is only available if the text field is not empty!

Remove

Lets you remove the currently selected key(s) from the list. The Remove button is only available if an item is currently selected in the keys list.