streamalism.org

1. Oversigt

I denne artikel taler vi om en kerneegenskab i Java-sproget - standardkommentarerne, der er tilgængelige i JDK.

2. Hvad en kommentar er

Kort sagt, kommentarer er Java-typer, der indledes med et "@" symbol.

Java har haft annoteringer lige siden udgivelsen 1.5. Siden da har de formet den måde, vi har designet vores applikationer på.

Spring og Hibernate er gode eksempler på rammer, der er stærkt afhængige af annoteringer for at muliggøre forskellige designteknikker.

I bund og grund, en kommentar tildeler ekstra metadata til den kildekode, den er bundet til. Ved at tilføje en kommentar til en metode, interface, klasse eller felt kan vi:

1. Informer compileren om advarsler og fejl
2. Manipuler kildekode på kompileringstidspunktet
3. Ændre eller undersøge adfærd ved kørsel

3. Java-indbyggede kommentarer

Nu hvor vi har gennemgået det grundlæggende, lad os se på nogle kommentarer, der leveres med kernen Java. For det første er der flere, der informerer kompilering:

1. @Override
2. @SuppressWarnings
3. @Forældet
4. @SafeVarargs
5. @FunktionelInterface
6. @Hjemmehørende

Disse annoteringer genererer eller undertrykker kompilatoradvarsler og -fejl. At anvende dem konsekvent er ofte en god praksis, da tilføjelse af dem kan forhindre fremtidig programmeringsfejl.

Det @Override annotering bruges til at indikere, at en metode tilsidesætter eller erstatter en arvet metodes opførsel.

@SuppressWarnings angiver, at vi vil ignorere visse advarsler fra en del af koden. Det @SafeVarargs annotering virker også på en type advarsel relateret til brug af varargs.

Det @Forældet annotering kan bruges til at markere en API, som den ikke længere er beregnet til brug. Desuden er denne kommentar blevet eftermonteret i Java 9 for at repræsentere mere information om afskrivningen.

For alle disse kan du finde mere detaljeret information i de linkede artikler.

3.1. @FunktionelInterface

Java 8 giver os mulighed for at skrive kode på en mere funktionel måde.

Single Abstract Method-grænseflader er en stor del af dette. Hvis vi har til hensigt, at et SAM-interface skal bruges af lambdas, kan vi eventuelt markere det som sådan med @FunktionelInterface:

@FunctionalInterface offentlig grænseflade Adder {int tilføj (int a, int b); }

Synes godt om @Override med metoder, @FunktionelInterface erklærer vores intentioner med Adder.

Nu, om vi bruger @FunktionelInterface eller ej, kan vi stadig bruge Adder på samme måde:

Adderadder = (a, b) -> a + b; int resultat = adder.add (4,5);

Men hvis vi tilføjer en anden metode til Adder, så klager compileren:

@FunctionalInterface offentlig grænseflade Adder {// compiler klager over, at grænsefladen ikke er en SAM int-tilføjelse (int a, int b); int div (int a, int b); }

Nu ville dette have kompileret uden @FunktionelInterface kommentar. Så hvad giver det os?

Synes godt om @Override, denne kommentar beskytter os mod fremtidig programmeringsfejl. Selvom det er lovligt at have mere end en metode på en grænseflade, er det ikke når grænsefladen bruges som et lambda-mål. Uden denne kommentar ville compileren bryde de snesevis af steder, hvor Adder blev brugt som lambda. Nu, det bryder bare ind Adder sig selv.

3.2. @Hjemmehørende

Fra og med Java 8 er der en ny kommentar i java.lang.annotation pakke kaldet Hjemmehørende. Det @Hjemmehørende annotering gælder kun for felter. Det angiver, at det kommenterede felt er en konstant, der kan henvises til fra den oprindelige kode. For eksempel er her, hvordan det bruges i Heltal klasse:

offentlig finaleklasse Heltal {@Native public static final int MIN_VALUE = 0x80000000; // udeladt}

Denne kommentar kan også tjene som et tip til værktøjerne til at generere nogle ekstra headerfiler.

4. Meta-kommentarer

Dernæst er metanoteringer annoteringer, der kan anvendes på andre annoteringer.

Disse meta-annotationer bruges for eksempel til annoteringskonfiguration:

1. @Mål
2. @Tilbageholdelse
3. @Arvet
4. @Dokumenteret
5. @Gentagelig

4.1. @Mål

Anmærkningerne kan variere afhængigt af kravene. Mens en kommentar kun bruges med metoder, kan en anden kommentar forbruges med konstruktør- og feltdeklarationer.

For at bestemme målelementerne i en brugerdefineret kommentar skal vi mærke den med en @Mål kommentar.

@Mål kan arbejde med otte forskellige elementtyper. Hvis vi ser på kildekoden til @SafeVarargs, så kan vi se, at det kun skal være knyttet til konstruktører eller metoder:

@Documented @Retention (RetentionPolicy.RUNTIME) @Target ({ElementType.CONSTRUCTOR, ElementType.METHOD}) offentlig @interface SafeVarargs {}

4.2. @Tilbageholdelse

Nogle kommentarer er beregnet til at blive brugt tip til compileren, mens andre bruges ved kørselstid.

Vi bruger @Tilbageholdelse kommentar for at sige, hvor i vores programs livscyklus vores kommentar gælder.

For at gøre dette skal vi konfigurere @Tilbageholdelse med en af ​​tre fastholdelsespolitikker:

1. RetentionPolicy.SOURCE - hverken synlig for compileren eller runtime
2. RetentionPolicy.CLASS - synlig af kompilatoren
3. RetentionPolicy.RUNTIME - synlig af compileren og runtime

@Tilbageholdelse som standard RetentionPolicy.SOURCE.

Hvis vi har en kommentar, der skal være tilgængelig ved kørsel:

@Retention (RetentionPolicy.RUNTIME) @Target (TYPE) offentlig @interface RetentionAnnotation {}

Så hvis vi tilføjer nogle kommentarer til en klasse:

@RetentionAnnotation @ Forældet offentlig klasse AnnotatedClass {}

Nu kan vi reflektere over Annoteret klasse for at se, hvor mange kommentarer der er bevaret:

@Test offentligt ugyldigt nårAnnotationRetentionPolicyRuntime_shouldAccess () {AnnotatedClass anAnnotatedClass = new AnnotatedClass (); Annotation [] annotations = anAnnotatedClass.getClass (). GetAnnotations (); assertThat (annotations.length, er (1)); }

Værdien er 1 fordi @RetentionAnnotation har en opbevaringspolitik på KØRETID mens @Forældet ikke.

4.3. @Arvet

I nogle situationer har vi muligvis brug for en underklasse for at binde kommentarerne til en overordnet klasse.

Vi kan bruge @Arvet kommentar for at få vores kommentar til at sprede sig fra en kommenteret klasse til dens underklasser.

Hvis vi ansøger @Arvet til vores brugerdefinerede kommentar og derefter anvende den på BaseClass:

@Inherited @Target (ElementType.TYPE) @Retention (RetentionPolicy.RUNTIME) public @interface InheritedAnnotation {} @InheritedAnnotation public class BaseClass {} public class DerivedClass udvider BaseClass {}

Derefter, efter at have udvidet BaseClass, skal vi se det DerivedClass ser ud til at have den samme kommentar ved kørsel:

@Test offentlig ugyldig nårAnnotationInherited_thenShouldExist () {DerivedClass derivClass = new DerivedClass (); InheritedAnnotation annotation = derivatedClass.getClass () .getAnnotation (InheritedAnnotation.class); assertThat (annotation, instanceOf (InheritedAnnotation.class)); }

Uden @Arvet kommentar, ovenstående test mislykkedes.

4.4. @Dokumenteret

Som standard dokumenterer Java ikke brugen af ​​en kommentar i Javadocs.

Men vi kan bruge @Dokumenteret kommentar for at ændre Java's standardadfærd.

Hvis vi opretter en brugerdefineret kommentar, der bruger @Dokumenteret:

@Documented @Target (ElementType.FIELD) @Retention (RetentionPolicy.RUNTIME) offentlig @interface ExcelCell {int-værdi (); }

Og anvend det på det relevante Java-element:

offentlig klassemedarbejder {@ExcelCell (0) offentlig strengnavn; }

Derefter Medarbejder Javadoc vil afsløre brug af annotering:

4.5. @Gentagelig

Nogle gange kan det være nyttigt at angive den samme kommentar mere end én gang på et givet Java-element.

Før Java 7 var vi nødt til at gruppere annoteringer sammen i en enkelt container-kommentar:

@Schedules ({@Schedule (time = "15:05"), @Schedule (time = "23:00")}) ugyldig planningAlarm () {}

Imidlertid bragte Java 7 en renere tilgang. Med det @Gentagelig kommentar, vi kan lave en kommentar, der kan gentages:

@Repeatable (Schedules.class) public @interface Schedule {String time () default "09:00"; }

At bruge @Gentagelig, er vi også nødt til at have en containerangivelse. I dette tilfælde genbruger vi det @Planer:

public @interface Schedules {Schedule [] value (); }

Selvfølgelig ser det meget ud som det, vi havde før Java 7. Men værdien nu er, at indpakningen @Planer er ikke specificeret længere, når vi skal gentage @Tidsplan:

@Schedule @Schedule (time = "15:05") @Schedule (time = "23:00") ugyldig planningAlarm () {}

Fordi Java kræver wrapper-annotering, var det let for os at migrere fra pre-Java 7-annoteringslister til gentagelige annoteringer.

5. Konklusion

I denne artikel har vi talt om indbyggede Java-kommentarer, som enhver Java-udvikler skal være fortrolig med.

Som altid kan alle eksemplerne i artiklen findes på GitHub.