28

Is there a common or standard annotation in Java for methods that, while defined, have yet to be implemented?

So that, for instance, if I were using a pre-alpha version of a library that contained something like

@NotImplementedYet
public void awesomeMethodThatTotallyDoesExactlyWhatYouNeed(){ /* TODO */ }

I'd get a compile-time warning when trying to call awesomeMethodThatTotallyDoesExactlyWhatYouNeed?

rampion
  • 87,131
  • 49
  • 199
  • 315
  • 3
    Most libraries simply won't expose that method at all. What would be the point? – Louis Wasserman Apr 02 '12 at 21:49
  • 2
    I've encountered it, [as a user](https://github.com/NICTA/scoobi/issues/71). Maybe to float the future API as an idea, get users ready for it? – rampion Apr 02 '12 at 21:51
  • You could, of course, create your own "@NotImplementedYet" annotation, and use it however you want: http://docs.oracle.com/javase/1.5.0/docs/guide/language/annotations.html – paulsm4 Apr 02 '12 at 21:54
  • Related: [*Is there anything like .NET's NotImplementedException in Java?*](https://stackoverflow.com/q/2329358/642706) – Basil Bourque Feb 23 '19 at 03:02

4 Answers4

19

You might want to use UnsupportedOperationException and detect calls to-yet-to-be-implemented methods when running your tests.

Alexander
  • 23,432
  • 11
  • 63
  • 73
  • 4
    OP is looking for an annotation that will tell the caller at compile time that the method will throw `UnsupportedOperationException`. As other side creating such an annotation is easy, he is looking for something that is accepted as convention – Miserable Variable Apr 02 '12 at 22:17
  • Not exactly the solution requested but better than nothing, and somewhat orthogonal (better in other ways). – bbarker Oct 28 '15 at 19:28
3

No, there is no standard annotation specifically for methods that have yet to be implemented.

However, there is a more general annotation in the JDK that marks an API which developers are discouraged from using, and the Java compiler itself can issue warnings when it is used. I am talking about @Deprecated, which many developers only think of as "announcing removal". However, the relevant articles in the JDK docs (e.g. for Java 7 and Java 9) list several example use cases, only one of them being about removal:

  • The API is dangerous (for example, the Thread.stop method).

  • There is a simple rename (for example, AWT Component.show/hide replaced by setVisible).

  • A newer, better API can be used instead.

  • The deprecated API is going to be removed.

I think your case "not implemented yet" certainly goes in the same direction as those. Further, if the method would always throw a NotYetImplementedException, it even fits the example "The API is dangerous".

So all you need to do is the following:

  1. Add @Deprecated to the method
  2. Add @deprecated Javadoc to explain the background
  3. Configure your build to invoke the compiler with -Xlint:deprecation so that it issues warnings.
Jens Bannmann
  • 4,845
  • 5
  • 49
  • 76
2

You could create your own annotation. With the runtime retention policy you can then configure target builds to know to look for this annotation, if necessary. 

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Target({
    ElementType.ANNOTATION_TYPE, 
    ElementType.METHOD, 
    ElementType.CONSTRUCTOR,
    ElementType.FIELD})
@Retention(RetentionPolicy.RUNTIME)
public @interface Unimplemented {

    boolean value() default true;
}
mhradek
  • 1,376
  • 14
  • 19
1

Google libraries use the @Beta annotations for API that is likely to change but the methods are implemented though

Andrejs
  • 26,885
  • 12
  • 107
  • 96