runt18 / jsr-305 Goto Github PK

What steps will reproduce the problem?
1. Open TypeQualifierNickname.java

What is the expected output? What do you see instead?
TypeQualifierNickname lacks @Retention(RetentionPolicy.RUNTIME)

What version of the product are you using? On what operating system?
r43

Please provide any additional information below.
All other annotations like TypeQualifier have runtime retention policy.
TypeQualifierNickname doesn't and thus - it cannot be examined by reflection

What steps will reproduce the problem?
1. Create project javadoc using your preferred approach.
2. Review documentation for these classes vs. their source.

What is the expected output? What do you see instead?
One would hope to find the class-level descriptions of these annotations, but 
they are missing.  This is arguably a bug specific to a given javadoc 
implementation, but the generated javadocs at 
http://code.google.com/p/jsr-305/source/browse/#svn%2Ftrunk%2Fjavadoc suffer 
from the same peculiarity as those I built locally anyway, the basic usage 
examples for annotations at 
http://docs.oracle.com/javase/1.5.0/docs/guide/language/annotations.html imply 
that javadoc should precede annotations, and the remainder of the jsr-305 API 
codebase follows this practice.

What version of the product are you using? On what operating system?
svn trunk rev 51.

Please provide any additional information below.

> What steps will reproduce the problem?
1. perform getAnnotations at runtime, they will not be found as they have
RetentionPolicy.CLASS retention.

> What is the expected output? What do you see instead?
This information is useful at runtime.

One use is runtime validation of information from external sources e.g.
user input, data from other services, configuration files.

Another use is controlling serialization. I have an Immutable annotation I
use which changes how a class is serialized. (using custom serialization)
For Immutable classes, all instances which are equals() become the same
instance on deserialization. For other classes, identity == is used.

This project contains a few files that are licensed under a CC licence:

  ri/src/main/java/javax/annotation/concurrent/Immutable.java
  ri/src/main/java/javax/annotation/concurrent/GuardedBy.java
  ri/src/main/java/javax/annotation/concurrent/NotThreadSafe.java

To package jsr-305 in Fedora, we add a licence file:

  http://pkgs.fedoraproject.org/cgit/jsr-305.git/tree/NOTICE-CC-BY.txt

Could this be added to the Subversion repo? That would avoid us having to 
maintain a Fedora-specific patch.

These Numbers can have overflow and rounding errors if converted to an int
value.  A double is the safest default choice. (Even for long it should be
fine.)

The following program prints
forConstantValue(-1) is NEVER
forConstantValue2(-1) is NEVER
forConstantValue(-0.1) is ALWAYS // rounded to 0.
forConstantValue2(-0.1) is NEVER
forConstantValue(-9999999999) is NEVER
forConstantValue2(-9999999999) is NEVER
forConstantValue(-999999999999) is ALWAYS // overflow to a postive number.
forConstantValue2(-999999999999) is NEVER
forConstantValue(9999999999) is ALWAYS
forConstantValue2(9999999999) is ALWAYS
forConstantValue(999999999999) is NEVER // overflow to a negative number.
forConstantValue2(999999999999) is ALWAYS
forConstantValue(NaN) is ALWAYS // Is not signed e.g. should fail @Signed test.
forConstantValue2(NaN) is UNKNOWN

public static void main(String... args) {
    for (Number n : new Number[]{
            new BigDecimal("-1"),
            new BigDecimal("-0.1"),
            new BigInteger("-9999999999"),
            new BigInteger("-999999999999"),
            new BigInteger("9999999999"),
            new BigInteger("999999999999"),
            Double.NaN,
    }) {
        System.out.println("forConstantValue(" + n + ") is " +
forConstantValue(n));
        System.out.println("forConstantValue2(" + n + ") is " +
forConstantValue2(n));
    }
}

// from Nonnegative
public static When forConstantValue(Object v) {
    if (!(v instanceof Number))
        return When.NEVER;
    boolean isNegative;
    Number value = (Number) v;
    if (value instanceof Long)
        isNegative = value.longValue() < 0;
    else if (value instanceof Double)
        isNegative = value.doubleValue() < 0;
    else if (value instanceof Float)
        isNegative = value.floatValue() < 0;
    else
        isNegative = value.intValue() < 0;

    if (isNegative)
        return When.NEVER;
    else
        return When.ALWAYS;
}

public static When forConstantValue2(Object v) {
    if (!(v instanceof Number))
        return When.NEVER;


    double value = ((Number) v).doubleValue();
    if (Double.isNaN(value))
        return When.UNKNOWN;
    else
        return value < 0 ? When.NEVER : When.ALWAYS;
}

> What steps will reproduce the problem?
1. run the program above 

> What is the expected output? 
forConstantValue2

> What do you see instead?
In valid conversion of BigInteger and BigDecimal

What steps will reproduce the problem?
1. Get a snapshot of the subversion repository
2. mvn javadoc:javadoc

What is the expected output? What do you see instead?
The output should be free of warnings.  However, the output contains a
number of javadoc warnings.  The web pages produced by javadoc also contain
a number of typographical errors.

What version of the product are you using? On what operating system?
I am using a Subversion snapshot as of 5 Nov 2007 on Linux (Fedora 8).

Please provide any additional information below.
The attached patch fixes the javadoc issues.

A new annotation would be nice to mark a piece of code for deadlock problems.

example:

@NeverBy("this")
Object canCauseDeadlock = ...

...
synchronized (this) {
   canCauseDealock...   // <-- Warning
}


https://github.com/google/error-prone/issues/366

If Immutable does not have RetentionPolicy.RUNTIME then there is no easy way to 
test for immutability.

I've been writing a Test-by-Contract JUnit system which would be able to test 
for Immutability, but this is dependent upon @Immutable, and perhaps a few 
other annotations, being available at runtime.

Some annotations need to be clear what they do and how they are expected to
be used.

For example, I don't know if this will do anything or not.

@Notnull
public enum CannotBeNull {
   YES, NO
}

What steps will reproduce the problem?
1. NA
2.
3.

What is the expected output? What do you see instead?

The published POM file at
"http://repo2.maven.org/maven2/com/google/code/findbugs/jsr305/1.3.8/jsr305-1.3.
8.pom"
has the <artifactId> of "findbugs".  Expected "jsr305".  It looks like this
file is a copy of the findbugs POM at
"http://repo2.maven.org/maven2/com/google/code/findbugs/findbugs/1.3.8/findbugs-
1.3.8.pom"

What version of the product are you using? On what operating system?

1.3.8 on Ubuntu 9.04

Please provide any additional information below.

The API documentation for toString is rather weak.  Although toString is 
part of the public API for every object, not every object implements 
toString for public consumption.

We need an annotation that will denote when toString returns values are 
subject to change without warning.  This allows developers to be confident 
that API users are not parsing output of toString for values, when the 
toString implementation was designed for debugging purposes.  For 
instance, Component subclasses produce a list of parameters and values are 
part of their toString.  There is no specification on the order or content 
of these values.  They can change from revision to revision.  Any client 
code relying on such a toString implementation should be considered 
fragile (at best).

I recommend that a @Volatile annotation for such a case.  Though @Volatile 
might be confused with the keyword and/or connote some expectation of 
concurrecy, so another annotation name is probably better (but it's a 
place to start).

[deleted issue]

What steps will reproduce the problem?
BigDecimal d = new BigDecimal("4.0");
BigDecimal e = new BigDecimal("4.00");

System.out.println(d.compareTo(e) == 0); //true
System.out.println(d.equals(e)); //false

From the Comparable.compareTo documentation:
It is strongly recommended, but not strictly required that (x.compareTo(y)
==0) == (x.equals(y)). Generally speaking, any class that implements the 
Comparable interface and violates this condition should clearly indicate 
this fact. The recommended language is "Note: this class has a natural 
ordering that is inconsistent with equals." 

We need an annotation that clearly denotes that the result is inconsistent 
with equals.  I recommend @InconsistentWithEquals.

In the following example, the type checked can be obtained from the
generic. The generic helps ensure the type is consistent.

public static void main(String... args) {
    System.out.println("getTypeQualifier(MatchesPattern.Checker.class)= " +
getTypeQualifier(MatchesPattern.Checker.class));
}

public static Type getTypeQualifier(Class<? extends TypeQualifierValidator>
tqvClass) {
    for (Type type : tqvClass.getGenericInterfaces()) {
        if (type instanceof ParameterizedType) {
            ParameterizedType parameterizedType = (ParameterizedType) type;
            if (parameterizedType.getRawType() == TypeQualifierValidator.class)
                return parameterizedType.getActualTypeArguments()[1];
        }
    }
    throw new AssertionError();
}

public interface TypeQualifierValidator<A extends Annotation, T> {
    public
    @Nonnull
    When forConstantValue(@Nonnull A annotation, T value);
}

@Documented
@Retention(RetentionPolicy.RUNTIME)
public @interface MatchesPattern {
    @RegEx
    String value();

    int flags() default 0;

    static class Checker implements TypeQualifierValidator<MatchesPattern,
String> {
        @Nonnull
        public When forConstantValue(MatchesPattern annotation, String value) {
            Pattern p = Pattern.compile(annotation.value(),
annotation.flags());
            if (p.matcher(value).matches())
                return When.ALWAYS;
            return When.NEVER;
        }

    }
}

If you read concrete classes its not always clear whether a member is
delibrately package local or left unspecified.

Members left unspecified can often be made private or even deleted
(checking for unused private members is simpler than unused package local
members)

Some members can appear that private is okay, however for performance
reasons may have been delibrately made package local. e.g. a member which
is accessed by an inner class can perform better if package local rather
than private (due to the use of accessor methods)

To address this I suggest a @package_local annotation to signify that a
member is explicity package local.

Will be an annotation to suggest implementation of equals/hashCode in all
implementations of an interface (all subclasses of a class, including itself)?
It might be useful to reduce error caused by using the default
implementation of equals/hashCode methods.

(I am not sure whether it is useful to have an annotation only for concrete
implementations, and one another requiring them on both abstract and
concrete implementations too.)

Is might be also useful similar to toString methods.

> What steps will reproduce the problem?
1. Try to utilise JSR 303 and JSR-305 at the same time.

> What is the expected output? 
One annotation for a given meaning.

> What do you see instead?
Two or more annotations for the same thing.  Without a single standard
existing uses are likely pick one or the other.

e.g. void method(@javax.annotations.Notnull @java.validation.NotNull
@org.jetbrains.annotations.NotNull String text);

JSR-305 also defines/suggests a Contraint validation.
e.g. Pattern(regex=, flags=) 

I recommend that we add a "value" field to annotations accepting the 
javax.annotation.meta.When value.  This allows more succinct (and I feel 
readable) code such as:

@Nonnull(When.ALWAYS) instead of @Nonnull(when = When.ALWAYS) code.  The 
alternative is to import the fields from When, yielding @Nonnull(when=ALWAYS), 
which is about equivalent, but I feel the value option is more idiomatic, where 
available.

Accidental method access widening is a big problem.  Often the consequence 
is that the API is cluttered with additional (and unnecessary) public 
methods, but in some cases widening could lead to unexpected 
interactions.  JCompoent.paintComponent method is frequently overridden 
and widened to no useful effect.  Such an annotation would provide the 
user with a clear warning that he has done something unexpected.

Conversely, there is the case where we expect that the access is widened 
(to public).  The ever-problematic Object.clone is such a method.  Users 
should be warned if they override Object.clone, but do not widen access to 
the method.

I am proposing the addition of two annotations:
AccessWideningProhibited
AccessWideningRequired

Theorectically, we could also include the middle ground, but that seems 
overwrought to me:
AccessWideningPermitted

Thanks,

Karl Schaefer

For thread safe components, I like to document the type of thread safety. 
This information could be checked staticly.
e.g.
- The caller is responsible for thread safety. This could check the caller
actually does this is some way. e.g. has a ThreadSafety annotation.
- Locking is global by a static lock.
- Locking allows one thread at a time per instance
- Locking allows concurrent read (one thread writing)
- Locking allows concurrent reading and writing.
- State is thread local.
- The class/object is stateless.
- The thread safety cannot be determined staticly.

Currently, there is only two annotations ThreadSafe and NotThreadSafe with
no distiction, or checking of the type of thread safety.

The annotations are very useful even now - if only to serve as documentaion
before any tools uses them

Can you please upload the artefacts to the central maven repository
(repo1.maven.org)?

Hi.

I've been using javax.annotation.Nullable and javax.annotation.Nonnull in my 
code, as they're IDE neutral and capable of being recognized by several popular 
tools.

However, Java 1.8 requires that inner-class and qualified type references use 
an annotation syntax which is compatible with it's new JSR-308 support (e.g. A 
"@Nullable MyOuterClass.MyInnerClass" parameter becomes "MyOuterClass.@Nullable 
MyInnerClass").

Doing that with the JSR-305 annotations causes javac to complain "annotation 
type not applicable to this kind of declaration", and Eclipse to complain 
"Annotation types that do not specify explicit target element types cannot be 
applied here".

This is because the JSR-305 annotation definitions lack a declaration of the 
form:

@java.lang.annotation.Target({ java.lang.annotation.ElementType.FIELD, 
java.lang.annotation.ElementType.METHOD, 
java.lang.annotation.ElementType.PARAMETER, 
java.lang.annotation.ElementType.LOCAL_VARIABLE })

While JSR-305 may not currently be moving forward as an official standard, it's 
still of great value to many people as a defacto one, so if there is any way 
@Target could be added in order for that to continue with Java 1.8 until 
something more official comes along, it would be most excellent.

Many thanks for your consideration.

Currently ThreadSafe has a Target of TYPE, however and additional type of
METHOD should be useful for complex situations (which are the sort of thing
you want to docuement)

An example,

I have a class which is thread safe, however I want the ability to
shutdown/close the resource even if it is locked by another thread.  This
method is inherently NOT thread safe as I don't want the closing thread to
get blocked.  This should be documented and handled with care.

What steps will reproduce the problem?
1. check out ri from svn
2. mvn clean install

What is the expected output? What do you see instead?
no source or javadoc jars!  Friendly mvn builds provide these.


What version of the product are you using? On what operating system?
latest 0.1-SNAPSHOT source from trunk

Please provide any additional information below.

What steps will reproduce the problem?
1. Get a snapshot of the subversion repository
2. mvn compile

What is the expected output? What do you see instead?
The output should show a successful compile.  Instead, the compile fails
while trying to build the sample use cases.

What version of the product are you using? On what operating system?
I am using a subversion snapshot as of 5 Nov 2007 on Linux (Fedora 8).

Please provide any additional information below.
The attached patch fixes the problem.

What steps will reproduce the problem?

1. Open Nonnegative.java
2. Look at inner class Checker

What is the expected output? What do you see instead?

Class Checker should be static, just like all other checkers

What version of the product are you using? On what operating system?

r43