Common license preamble for all Java classes

[chenejac]

Is your feature request related to a problem? Please describe. There is a license preamble in a lot of Java files. Moreover, it is not in all Java files, meaning it is not consistent.

Describe the solution you'd like Remove those lines, and generate common JavaDoc preamble for all classes

Additional context @wwelling wrote: Looks to be a JavaDocs license header to not repeat license text in all files. Here are some links trying to discover the origin of these comments:

https://www.oracle.com/technical-resources/articles/java/javadoc-tool.html#packagecomments https://mavenlibs.com/javadoc/api/org.sonarsource.license-headers/license-headers

[kaladay]

The javadoc link from above references the use of package.html. This seems a bit outdated and I am using package-info.java instead.

The Java 7 documentation for package comment seems to be the clearest in this regard.

The Java 11 documentation for package comment is a bit more lacking in details.

The FAQ (See A19) describes some limitations that they decided to not fix.

From what I understand between all of this is that removing the license from the class and putting it in the package java doc will result in the following design and behavior:

• The generated classes docs will not show any copyright information.
• The class files themselves will not show copyright information.
• The generated package docs (generated as package-summary.html) will contain the copyright information.
• The generated package docs are only per the specific package and there is no inheritence.
• A package-info.java or a package.html file must be created for every single package.
• A package-info.java appears to work for me.
• A package.html file does not appear to work for me.

Is this the desired behavior?

The mavenllibs link above has practically no documentation and is specialized towards SonarSource. It utilizes pre-created licenses files that are specific to SonarSource and does not include the Vivo LICENSE file.

Their github project appears to be here:

• https://github.com/SonarSource/license-headers

[chenejac]

Can someone list some popular projects using the approach with JavaDoc? After reading a little bit about that, it looks to me as the traditional way with preamble in all Java files is more safe for us. I am not a lawyer, but it looks as adding copyright and reference to license at the beginning of each source file is needed or at least a good practice - link. I think we should just make our preamble consistent, with a short text /* $This file is distributed under the terms of the license in the LICENSE file in the root of this project$ */

[kaladay]

@chenejac I found this after trying some different search strings this morning:

• https://forums.oracle.com/ords/apexds/post/how-best-to-include-a-copyright-in-javadoc-2291

• Copyright.java (interface defining a few constants such as default copyright date, default owner, etc. as well as the full default copyright notice)
• CopyrightAnnotation.java (annotation type for marking code as copyrighted)
• CopyrightTaglet.java (taglet for adding "@copyright" tags in JavaDoc)

  
  package org.sample.legal;

import com.sun.tools.doclets.Taglet; import com.sun.javadoc.*; import java.util.Map;

/**

• Represents the "@Copyright" tag. If empty, the default copyright notice
• will be displayed.
• tag can be used in any overview, package, class, or interface
• {@link com.sun.javadoc.Doc}. This is not an inline tag.

• tag can display a default value, the default value modified with
• a different copyright date, or a completely custom value. To display the
• default value, use "@Copyright" alone.

• pecify a different date, enter the copyright years separated by
• dashes (-) or commas (,); optional spaces are allowed. For example, the
• following will be recognized as valid dates:

• 2. "@Copyright 1999"
  4. "@Copyright 1999, 2000"
  6. "@Copyright 2001-2003
  8. "@Copyright 2001-3, 2005
• isplay a completely custom value, simply enter whatever text is to be
• displayed after the "@Copyright" tag.

• text is displayed in italics to remind the reader of its
• importance.

• @Copyright */ @CopyrightAnnotation public class CopyrightTaglet implements Copyright, Taglet {

private static final String NAME = "Copyright"; private static final String HEADER = "Copyright:";

[kaladay]

This is not from Java files, but I happened to notice this while working on another issue.

There are .ftl template files with lines like:

<#-- $This file is distributed under the terms of the license in /doc/license.txt$ -->

Which I neither see a doc directory nor a license.txt directory anywhere in the project source code.

[brianjlowe]

My memory's a bit hazy, but I seem to recall that back a decade or so ago we had that license header line in any kind of source file with a commenting mechanism that permitted it. The old ant build would then replace the line with the contents of /doc/license.txt at build time, so the things like installed JSPs and later Freemarker templates would have the full license text automatically inserted. I think that was removed at some point because it made bug reports difficult when the line numbers would shift between the source tree and the webapps directory. It does seem like it would make sense to retain the license comments with an updated path to the license.

[chenejac]

@kaladay I think we need the simple preamble

1. At the beginning of each Java file /* $This file is distributed under the terms of the license in LICENSE$ */
2. At the beginning of each ftl file <#-- $This file is distributed under the terms of the license in LICENSE$ -->

@kaladay can you please investigate how alignment of files in accordance with two points above can be automatized in IDEs (through code formatter or in some other way)? I believe adding of license preamble might produce a lot of changed files, and maybe we can run that after the sprint together with code style alignment.

[chenejac]

Also, it would be nice to have checking of the existence of license by using licence-maven-plugin - https://github.com/DSpace/DSpace/blob/main/pom.xml#L419

[chenejac]

We decided to postpone this issue. It should be also discussed with VIVO Leadership group. Checking licence header might be part of building process (licence-maven-plugin). Aligning existing code base with licence header might be done by using some IDE plugins (https://www.jetbrains.com/help/idea/copyright.html#copyright-profile, https://www.baeldung.com/eclipse-copyright-header)