Copyright Wizard is an Eclipse plugin allowing you to add header comments on
all or a selection of files of a project. Although the text of the comment is
completely free, plugin has been designed principally to add copyright text,
especially with the support of adapted substitution variables.
The copyright text can be applied to a selection of files belonging to one or
more projects. These files can be of different types. The wizard recognizes
the type of each file from the Eclipse ContentType and applies the relevant
comment format defined in the preferences of the tool.
In addition, the wizard can add to the selected projects a file containing the
text of the license chosen.
The wizard filters resources on which to apply the copyright. So any file whose
ContentType not inherits basic type Text are excluded, as well as all files
having a ContentType explicitly excluded in preferences. All files or folders
whose names begin with a dot are also excluded.
In addition to the automatic filters, the user can filter the files by patterns
(include and exclude patterns) on the filename and files already containing a
comment header, whatever the text of this comment.
The files retained by the filter are presented to the user, selected by default
for treatment. The user can modify the selection at the level of files or
directories proposed.
Treatment can be applied to several projects simultaneously. It is thus
possible to apply a copyright in a single treatment on all Eclipse projects
making a JEE project, for example.
The configuration of the plugin is registered in the Eclipse preferences, in the General section:
| Section | Description |
|---|---|
| Copyright |
This section allows you to define all the preconfigured texts of
copyright, and the associated licenses text file. The plug is pre-configured for installation with the main open source licences: EPL, APL, LPG and LGPL. |
| Header Formats |
This section is used to define the format of the comments in fontion
of the different file types. The plug is pre-configured for installation with the formats for files of Text, Java and XML types. |
Copyright parameters
The Copyright parameters allow to define a set of standard licenses, defining the text to be placed in the comment header of files, as well as a license file to add to the projects.
| Parameter | Description |
|---|---|
| Owner |
Sets the value of the substitution variable ${owner}. If not defined, it will take by default the same value that ${user} variable. |
| Licenses |
List of pre-configured licenses. Selecting an item on this list updates the fields in tabs. |
| Header text |
Tab to define the text of the comment to be placed in the header of
files. This text may contain substitution variables, which will be
replaced by their values at the time of insertion of the comment in
each target file.
|
| License file | Tab to set the (optional) license file to add to the projects. |
The License file tab allows you to associate a license file to a copyright definition:
| Parameter | Description |
|---|---|
| File name | Default name of the license file. The file name may be changed if desired by the user within the parameters of the wizard. |
| File content |
Text of the license. If the wanted file format is formatted, such as
HTML, the text must contain all the formatting tags. The contents of the file is not interpreted. Then the substitution variables do not apply here. |
The plugin is preconfigured with headers and licenses files for 4 open
source licenses: Eclipse, Apache, LPG and LGPL.
It is possible to add, change or delete any copyrights with the buttons Add,
Modify, and Delete:
- Add - Add a new Copyright. A dialog box opens for the input of the
label text under which will be registered the Copyright.
- Modify - Changing the label text of the copyright selected from the list.
- Delete - Remove the copyright selected from the list.
The 'Restore Defaults' button will reload the default copyrights
configuration file provided with the plug-in. All custom texts and copyrights
will be lost.
Header Formats parameters
The Header formats parameters are used to define the applicable format of
comment on headers for different types of files. The recognition of the type
of file is based on the Eclipse ContentType.
The formats apply only on the content in text format. If a format is not set
on a ContentType, it inherits the format of its parent, and so on recursively
until basic type Text.
To define a particular format on a file type, select the correspondent ContentType in the tree, and enter the definition of the format:
| Parameter | Description |
|---|---|
| Exclude this type from copyrights | If checked, all files defined by this ContentType will be automatically excluded by the wizard and will not have a copyright header. All other fields are then disabled. |
| First line | Format of the first line of the comment header. Typically this line contains no text and is composed of characters to draw a dividing line. |
| Line prefix | Format for the beginning of a comment line. This string will be placed by concatenation before all the lines of comment text defined in a text of copyrigt header, including blank lines. |
| Last line | Format of the last line of the comment header. Typically this line contains no text and is composed of characters to draw a dividing line. |
| Line format comment | Flag indicating if the comment header is in line format (checked) or block format (unchecked). For a comment in line format, it is important to define a valid "Line prefix" for the target language. |
| Do not override the first line |
Flag indicating whether, when inserting a comment in a file of the
selected type, the comment must begin on the first line (unchecked) or
on the second line (checked). Some languages require an instruction or a comment of a particular format on the first line of a source file. When checked, the content of the first line will be preserved by the wizard. |
| First line pattern |
Regular expression pattern to apply on the first line. If the line
matches, the comment is inserted after the line, else it is inserted
before. This pattern is optional. If it is leaved empty, the first line
is always skipped before to insert the comment header. The regular expression must respect the syntax defined by the Pattern java class. |
The labels to the right of the text entry fields indicate the length of the current content of the fields. These labels are particularly useful for long lines and lines containing spaces at the end.
The Clear button erases completely the format definition of the selected ContentType. It then inherits the format of its parent.
The 'Restore Defaults' button will reload the default formats definitions provided with the plug-in. All custom formats will be lost. By default the plug-in defines formats for 'Text', 'Java Source File' and 'Xml' content types, and excludes 'JAR Manifest File', 'ANT buildfile' and all content types defined by PDE and WTP plug-ins.
Copyright settings can be defined at the level of each project too, in the project properties. When defined, those settings are applied by default by the copyright wizard.
To defined project settings, open the project properties dialog and select the Copyright category. The properties page displayed contains two tabs.
Copyright settings are disabled by default. To enable, select the 'Enable project specific settings' checkbox. When enabled, a popup message is displayed proposing to import in the project settings the header formats definitions of the workspace. If you respond No, you will have to define all the header format, including the root Text content type.
When project settings are selected, the two tabs are enabled:
- Header text - The first tab allowes to define the header text that will be used by default for all the files in the project on which the wizard will apply a copyright. The same substitution variables that in workspace preferences can be used here. But there is no mean to define a different owner value, that has no sense at the project level, so using this variable must be avoided.
- Header formats - The second tab allowes to define the header comment format for all the content types deriving of the root Text type. This tab works exactly as the workspace preferences one.
The project copyright settings are saved in a file stored in the .settings directory of the project. Then this file can be saved in a SCM tool like CVS or Subversion and shared by a team.
The wizard is launched from the menu: Project -> Copyright Wizard...
First page - Projects selection
The first page of the wizard lets you select one or more projects on which to apply the copyright.
| Parameter | Description |
|---|---|
| Projects selection list | Projects having copyright settings are marked in the selection list by a "(C)" postfix on the projet name. |
| Override projects copyright settings | If checked, all projects copyright settings (headers text and formats) defined on selected projects will be override by the settings defined in the following page of the wizard. |
| Override only the header comment text |
This checkbox is enabled only if the previous one is checked. If checked, the override of project copyright settings is limited to the header comment text. All the header formats defined in the projects preferences will be used by the wizard for the corresponding projects. |
Second page - Copyright parameters
The second page of the wizard lets you define the parameters of copyright to
be applied to the selected projects.
It is possible to define a completely specific copyright, or select a
preconfigured copyright in the preferences of the wizard.
| Parameter | Description |
|---|---|
| Copyright type |
Selection list of copyright to apply. This list allows you to select one
of the preconfigured copyrights in the preferences, or to choose the
definition of a specific copyright (--- Custom copyright ---).
|
| Copyright header text |
Text of comment header to be applied to the selected files. This field
is pre-initialized with the text defined in preferences for the selected
copyright. It may, however, be changed if desired. The text should not contain formatting comment characters. |
| Include files |
Pattern of filenames on which apply the comment header. If leaved empty,
it is equivalent to "*" and all resources will be selected. It is possible to give several patterns, separated by commas. Then all resources corresponding at least to one of the patterns will be selected.  |
| Exclude files |
Pattern of filenames to exclude from the selection defined by the
include pattern. If leaved empty, there is no exclusion. It is possible to give several patterns, separated by commas. Then all resources corresponding at least to one of the patterns will be excluded.  |
| Replace existing headers |
This flag is used to indicate whether the wizard will replace the
existing header files (checked) or if they should not be modified
(unchecked). The recognition of the existence of a header comment in a file is made by comparing the 5 first characters in the first line of the file (or the second one if the parameter "Do not override the first line" is checked in the corresponding format) with the 5 first characters of the first line defined in the header comment format. |
| Add license file if not exists |
This flag allows you to add to selected projects a license file if no
file with the same name already exists. This parameter is usable only for preconfigured copyrights having a license file defined. |
| License file |
Name and path of the license file to create. This parameter is used only if the previous parameter has been selected. It is initialized by the file name defined in preferences settings for the selected copyright. |
Third page - Files selection
The wizard filters with the files patterns the files on which to apply the comment header. If the "Replace existing headers" has been checked, the files containing already a comment header are eligible for treatment. Otherwise they are also excluded from the pre-selection.
The last page of the wizard enables you to refine the selection. It presents the files filtered by the wizard.
The user has the possibility to unselect files or directories on which apply
the comment header.
In the previous screenshot, files config.properties and Sample2.java were
unselected and will therefore not be treated.
Finally click on Finish to start treatment on the selected files.
Example Java file before treatment:
Example Java file after treatment:
New with version 1.4, the copyright can also be applied directly to a selection of resources in the views for the selection of resources, such as the 'Navigator' or 'Package Explorer'.
If all resources are selected in projects for which a specific setting of copyrigth has been defined, the copyrigth is applied directly to these resources after confirmation by the user.
In either case, if at least one selected resource belongs to a project without specific setting of copyrigth, the wizard is opened. On the first page, the list of projects is limited to projects containing selected resources.
Also on the page of resource selection of the wizard, the list of resources is restricted to selected resources in the view. It is always possible to deselect some of the resources displayed. They will thus be excluded from the process of copyrigth application.
