When I run CheckStyle over my Java project it says Missing package-info.java file. for some classes, but not all of them. I can't really figure out why this message appears only sometimes. Furthermore my project runs perfectly fine without the package-info.java.
What does the package-info.java do? Do I really need it for my Java projects?
It is used to generate javadocs for a package.
/**
* Domain classes used to produce .....
* <p>
* These classes contain the ......
* </p>
*
* #since 1.0
* #author somebody
* #version 1.0
*/
package com.domain;
Will generate package info for com.domain package:
Example result: https://docs.oracle.com/javase/7/docs/api/java/awt/package-summary.html
Annotations
Another good reason to use package-info.java is to add default annotations for use by FindBugs. For instance, if you put this in your package-info file:
#DefaultAnnotation(NonNull.class)
package com.my.package;
then when findbugs runs on the code in that package, all methods and fields are assumed to be non-null unless you annotate them with #CheckForNull. This is much nicer and more foolproof than requiring developers to add #NonNull annotations to each method and field.
Not only some findbugs annotations, but a lot of java annotations in common libraries have the java.lang.annotation.ElementType.PACKAGE type as one of the possible values of their own java.lang.annotation.Target annotation, e.g.:
com.google.gwt.core.client.js.JsNamespace
com.querydsl.core.annotations.Config
com.sun.xml.bind.XmlAccessorFactory
groovy.transform.BaseScript
java.lang.Deprecated
javax.annotation.Generated
javax.xml.bind.annotation.XmlAccessorOrder
org.hibernate.annotations.TypeDef
net.sf.ehcache.pool.sizeof.annotations.IgnoreSizeOf
org.apache.hive.common.HiveVersionAnnotation
org.apache.wicket.authroles.authorization.strategies.role.annotations.AuthorizeAction
org.codehaus.commons.nullanalysis.NotNullByDefault
org.eclipse.persistence.oxm.annotations.XmlNameTransformer
org.glassfish.jersey.Beta
org.jgroups.annotations.Experimental
and much more.
This package-info.java file would be the file, where you can place such annotations (along with the javadoc).
A package-info.java file allows adding javadoc to document a whole package. See http://docs.oracle.com/javase/7/docs/api/java/applet/package-summary.html for example.
If you don't care about missing package documentation, then ignore the warning or disable the JavadocPackage check.
The package-info.java is a Java file that can be added to any Java source package. It is used to provide info at a "package" level as per its name.
It contains documentation and annotations used in the package.
javadoc example is already provided in the answer, the below part explains how it works incase of annotations.
For example, in the below file it is used to "substitute" the occurance of joda.time.DateTime with org.jadira.usertype.dateandtime.joda.PersistentDateTime
#TypeDefs({
#TypeDef(name = "PersistentDateTime", typeClass = PersistentDateTime.class, defaultForType=DateTime.class)})
package xyz.abc;
import org.hibernate.annotations.TypeDef;
import org.hibernate.annotations.TypeDefs;
import org.jadira.usertype.dateandtime.joda.PersistentDateTime;
import org.joda.time.DateTime;
There are a number of annotations available with which can be used to perform different things at "package" level. It can be found at https://docs.jboss.org/hibernate/orm/3.5/api/org/hibernate/annotations/package-summary.html
Related
I'm working with Google's Protocol Buffer (in combination with the Protocol Buffers maven plugin) which compiles a .proto file into a class. I can use the generated class in the default package perfectly, but not outside of it. I don't really know how to explain it any better so I'm going to show you some pictures.
I've tried subclassing the Hrp class but that doesn't work (the generated class is final). It is also not an option to move the class every time I re-generate the Hrp class.
I'm not sure if this is relevant, but the generated class is public final. It contains an empty, private constructor.
I have also tried setting the generated sources package prefix for the generated sources folder but that also does not work.
Any help would be greatly appreciated.
Try adding a package id to your Protocol Buffers definition. See Protocol Buffers Package
i.e.
syntax = "proto3";
package MyPackage;
option optimize_for = SPEED;
message Product {
repeated ASale sale = 1;
}
Then when you Generate the Java~Protocol~Buffers code (using protoc), it will be in package MyPackage and you will be able to import it into your java code in the normal way.
In java, you can not import anything from the Default package; which I believe is your problem. See How to access java-classes in the default-package?
I have a file which has only two statements in it
#javax.xml.bind.annotation.XmlSchema(namespace = "XXXXX", elementFormDefault = javax.xml.bind.annotation.XmlNsForm.QUALIFIED)
package sample;
want to create class file which has same name as filename is Package-info.java
package-info.java is not meant to be compilable. It is used by javadoc.
See http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/javadoc.html#packagecomment for more info:
Package Comment Files
Each package can have its own documentation comment, contained in its own "source" file, that the Javadoc tool will merge into the package summary page that it generates. You typically include in this comment any documentation that applies to the entire package.
To create a package comment file, you have a choice of two files to place your comments:
package-info.java - Can contain a package declaration, package annotations, package comments and Javadoc tags. This file is generally preferred over package.html.
package.html - Can contain only package comments and Javadoc tags, no package annotations.
A package may have a single package.html file or a single package-info.java file but not both. Place either file in the package directory in the source tree along with your .java files.
package-info.java - This file can contain a package comment of the following structure -- the comment is placed before the package declaration:
File: java/applet/package-info.java
/**
* Provides the classes necessary to create an
* applet and the classes an applet uses
* to communicate with its applet context.
* <p>
* The applet framework involves two entities:
* the applet and the applet context.
* An applet is an embeddable window (see the
* {#link java.awt.Panel} class) with a few extra
* methods that the applet context can use to
* initialize, start, and stop the applet.
*
* #since 1.0
* #see java.awt
*/
package java.lang.applet;
I want to write some tests for my compiler but can't get past an error.
I'm following an example from 'Implementing DSL with Xtext and Xtend' by L. Bettini (great book btw). I've downloaded the code for the 'entities' DSL from https://github.com/LorenzoBettini/packtpub-xtext-book-examples and the tests in EntitiesGenerator.xtend work great.
If I write a test for the default DSL (MyDsl) using the same code, I've got an error:
org.eclipse.xtext.xbase.compiler.CompilationTestHelper cannot be resolved to a type.
or, if I add org.eclipse.xtext.xbase.junit (2.4.1) to the list of required plug-ins, I get
Discouraged access: The type CompilationTestHelper is not accessible due to restriction on required project org.xtext.example.myDsl.tests
I can allow access to it, but then get a runtime error anyway. If I try to add org.eclipse.xtext.xbase.lib as well, only org.eclipse.xtext.xbase.lib.source appears in the list. I don't know it that matters. In any case, adding it doesn't change anything.
What do I need to do to make it work?
I'm using Juno with Xtext 2.4.1., Java 1.7.
The content of the test class:
package org.xtext.example.myDsl.tests
import com.google.inject.Inject
import org.eclipse.xtext.junit4.InjectWith
import org.eclipse.xtext.junit4.XtextRunner
import org.eclipse.xtext.xbase.compiler.CompilationTestHelper // error here
import org.xtext.example.myDsl.MyDslInjectorProvider
import org.junit.Test
import org.junit.runner.RunWith
#RunWith(typeof(XtextRunner))
#InjectWith(typeof(MyDslInjectorProvider))
class MyDslGeneratorTest {
#Inject extension CompilationTestHelper
#Test
def void testGeneratedCode() {
'''
Hello some1!
Hello some2!
'''.assertCompilesTo(
'''some content''')
}
}
Thank you in advance!
the xtext guys mark stuff that may be changed NOT as api. this is why you get this warning.
it should work anyway. (although it is meant to be used for xbase languages only)
P.S: you have to add a dependency to jdt.core too
I've made several attempts at getting package annotation #ParametersAreNonnullByDefault to work for me in a maven project but with no success.
Could someone share a link to a minimal/sample maven project where this is setup (or post the pom.xml and package-info.java and demo class)?
I'm talking about having findbugs processor enforce it for me.
How to apply #ParametersAreNonnullByDefault
Create a file package-info.java in your package where you want to enforce the desired behavior.
In that file, do the following:
/**
* You should do it like this!
*/
#ParametersAreNonnullByDefault
package com.stackoverflow;
import javax.annotation.ParametersAreNonnullByDefault;
How not to apply #ParametersAreNonnullByDefault
Don't do the following in a Java source file:
/**
* But you shouldn't do it this way!
*/
#ParametersAreNonnullByDefault
package com.stackoverflow;
import javax.annotation.ParametersAreNonnullByDefault;
public class Answer { ...
Declaring annotations like this is ambiguous.
Notes
It would be OK to apply the annotation directly on Answer class.
package com.stackoverflow;
import javax.annotation.ParametersAreNonnullByDefault;
/**
* You can do it like this also.
*/
#ParametersAreNonnullByDefault
public class Answer { ...
The exact same things apply to #ParametersAreNullableByDefault also.
For Android projects (for example when using libraries like Retrofit etc), this is the dependency to put in app/build.gradle (as mentioned by #Saket):
dependencies {
implementation 'com.google.code.findbugs:jsr305:3.0.2'
// ...
}
I use the javadoc #version tag in my classes, however I am not sure how to get the version in the class itself. Let's look at an example...
/**
* #version 1.0a
* #author Redandwhite
*/
public class JClass extends JFrame implements ActionListener, KeyListener {
String version = ...
}
Is there a method/class that can retrieve the version? Ideally, it's as simple as an API call which returns a simple String.
The javadoc comments are not included in the generated byte code in any form, so there is no way to access the value of the #version tag from Java code (unless you parse the source code of course). There might be a version annotation that can be used to specify the class version instead of or in addition to the javadoc #version tag, and this annotation would be accessible via the Java reflection API (i.e. Class.getAnnotations()).
As it's already been noted, it's not possible to get to that information.
An alternative solution is to read the Implementation-Version/Specification-Version property of the package.
That value can be defined in the MANIFEST.MF file of a jar file. If it is defined, then it can be queried for every package that's contained in that jar file.
So if you have a class org.example.MyClass and the jar it comes in has the relevant entries in the MANIFEST.MF file, then you can get the version like this:
Class<?> clazz = org.example.MyClass.class
Package pkg = clazz.getPackage();
String version = pkg.getImplementationVersion();