Dokumentation von Aufrufmöglichkeiten in Java
Das folgende Programm gibt eine mehr oder weniger zufällig ausgewählte double-Zahl zwischen 0 (einschließlich) und 1 (ausschließlich) aus.
Main.javapublic final class Main
{ public static void main( final java.lang.String[] args )
{ java.lang.System.out.println
( java.lang.Math.random() ); }}
Wie Felder, so werden auch Methoden in Java dokumentiert.
Die Dokumentation der Methode »java.lang.Math.random« findet man in der Dokumentation der Klasse »java.lang.Math«. Allgemein findet man (wie bei Feldern) die Dokumentation einer Methode in der Klasse der Methode.
- Dokumentation von »java.lang.Math.random()« (gekürzt und übersetzt)
- Modul java.base
- Packet java.lang
- Klasse Math
- Methodenzusammenfassung
static double random()
- Ergibt einen double-Wert größer oder gleich »0.0« und kleiner als »1.0«.
Man kann der Dokumentation der Klasse »Math« das Paket entnehmen, zu welchem die Klasse gehört, nämlich »java.lang«.
Außerdem kann man der Tatsache, daß die Methode »random« in der Dokumentation der Klasse beschrieben wird. entnehmen, daß jene Methode zu jener Klasse gehört.
Das Wort »public«
In manchen Beschreibungen findet man das Wort »public«. So liest man beispielsweise anstatt von »static double random()« manchmal auch die Beschreibung »public static double random()«. Das Wort »public« bedeutet, daß der Eintrag der Klasse nicht versteckt ist. Ein versteckter Eintrag ist ein Eintrag einer Klasse, der von Klienten nicht verwendet werden kann. Deswegen werden versteckte Einträge in der Dokumentation ohnehin auch normalerweise gar nicht angezeigt. Daher ist es auch oft überflüssig, das Wort »public« anzuzeigen, weil es in der Dokumentation normalerweise ohnehin selbstverständlich ist, daß alle dokumentieren Methoden »public« sind. Deswegen können wir das Wort »public« in der Dokumentation bis auf weiteres ignorieren.
Das Wort »static«
Das Wort »static« bedeutet, daß man die beschriebene Methode statisch ist, also daß man sie aufrufen kann, ohne daß man dafür ein Objekt benötigt. (Objekte werden in diesem Kurs erst später behandelt werden.)
Der Rückgabetyp (hier: »double«)
In der Dokumentation der Methode »random« steht der Typ des Aufrufs, nämlich »double«, vor dem einfachen Namen der Methode.
- Beschreibung von »java.lang.Math.random«
static double random()
Die Angabe »double« vor dem einfachen Namen »random« besagt, daß ein Aufrufausdruck dieser Methode, also der Ausdruck »java.lang.Math.random()« den Typ »double« hat.
Der Rückgabetyp ist der Typ des Aufrufs einer Methode. Er findet sich in der Dokumentation direkt vor dem eigentlichen Namen der Methode.
Die letzte Zeile dieser Dokumentation legt fest, daß der Wert eines Aufrufs stets größer als 0.0 oder gleich 0.0 und kleiner als 1.0, aber nicht 1.0 ist. (Dieser Wert kann höchstens 1−2⁻⁵³ , also 0,99999999999999988897769753748434595763683319091796875, sein.)
Eine Methode, deren Aufruf den Typ »int« hat, wird auch als eine „int-Methode“ bezeichnet. Dabei kann diese Art von Bezeichnung auch mit anderen Datentypen verwendet werden. Der Aufruf einer „double-Methode“ hat also den Typ »double«, und so weiter. Genauso ist aber auch eine Präfigierung mit anderen Eigenschaften möglich, so kann man auch von einer „Math-Methode“ sprechen, um auszudrücken, daß die Methode zur Klasse »java.lang.Math« gehört, und so weiter.
Wir schreiben bis auf weiteres Typen (wie »double«) nicht in den Quelltext. Die Typen dienen uns hier lediglich zur Beschreibung von Methoden.
Eine Ausnahme von der obigen Regel ist die Verwendung von Typnamen am Anfang qualifizierter Namen, wie in »java.lang.System.out.println()«, worin der Typname »java.lang.System« vorkommt.
Erweitertes Schaubild
Die Methode »java.lang.Math.random()« gehört zur Klasse »java.lang.Math«. Wir tragen sie unter Verwendung ihres Namens und einem Klammerpaar in ein schon früher vorgestelltes Schema mit einigen Namen ein.
- Das Ineinanderenthaltensein einiger bisher vorgestellten Namen
.----------------------------------------------------------.
| Paket "java.lang" |
| .------------------------------------------------------. |
| | Klasse "Integer" | |
| | .--------------------------------------------------. | |
| | | Feld "MAX_VALUE" | | |
| | '--------------------------------------------------' | |
| '------------------------------------------------------' |
| .------------------------------------------------------. |
| | Klasse "Long" | |
| | .--------------------------------------------------. | |
| | | Feld "MAX_VALUE" | | |
| | '--------------------------------------------------' | |
| '------------------------------------------------------' |
| .------------------------------------------------------. |
| | Klasse "Math" | |
| | .--------------------------------------------------. | |
| | | Feld "PI" | | |
| | | Feld "E" | | |
| | | Methode "random()" | | |
| | '--------------------------------------------------' | |
| '------------------------------------------------------' |
'----------------------------------------------------------'.----------------------------------------------------------.
| Paket "java.sql" |
| .------------------------------------------------------. |
| | Referenztyp "DatabaseMetaData" | |
| | .--------------------------------------------------. | |
| | | Feld "tableIndexStatistic" | | |
| | '--------------------------------------------------' | |
| '------------------------------------------------------' |
'----------------------------------------------------------'
Methoden und Felder
Vor den Methoden haben wir schon die ebenfalls dokumentierten Wertnamen (Felder) kennengelernt. Ein Methodenname ist kein Wertname und umgekehrt. Ob ein Name der Name einer Methode, wie »java.lang.Math.random()«. oder eines Feldes, wie »java.lang.Math.PI«, ist, kann der Dokumentation entnommen werden. Methodennamen stehen in der Dokumentation unter der Überschrift “Method Summary ” und stehen oft direkt vor einem Paar runder Klammern »()«, Wertnamen findet man unter der Überschrift “Field Summary ”.
Nicht aus der Dokumentation kopieren!
Ein Programmierer muß Dokumentationen von Methode verstehen, um dann die daraus gewonnenen Informationen zum Schreiben von Programmen verwenden zu können. Ein gelegentlicher Fehler von Anfängern, welche die Dokumentation noch nicht richtig verstehen, ist es, die Dokumentation einer Methode in ein Programm zu kopieren. Das ist in der Regel verkehrt.
Nicht aus der Dokumentation in den Quelltext kopieren!
(Wenn Sie etwas kopieren wollen, dann kopieren Sie besser ein Beispielprogramm aus der Lektion.)
Wir hatten schon früher einmal gesagt, daß wir Datentypen, wie »double«, bis auf weiteres nicht in Programm schreiben.
Der folgende Text zeigt, wie es aussehen kann, wenn ein Anfänger eine Beschreibung in sein Programm kopiert, wie dies öfter beobachtet wurde. Anfänger, die so vorgehen sind danach meist nicht in der Lage, das entstandene Programm noch selbständig zu korrigieren. Daher sollte es grundsätzlich vermieden werden, eine Beschreibung in den Quelltext zu kopieren.
- Text
public final class Main
{ public static void main( final java.lang.String[] args )
{ java.lang.System.out.println
( static double random() ); }}- Konsole (übersetzt)
Main.java:3: Fehler: unzulässiger Anfang eines Ausdrucks
{ java.lang.System.out.println
( static double random() ); }}
^
ein Fehler
Schon zuvor wurde ja ein Programmbeispiel vorgestellt, das zeigt, wie die Methode »java.lang.Math.random()« richtig aufgerufen wird. Wenn man sich das Programmieren durch Kopieren aus einer Vorlage erleichtern will, dann sollte man ein solches Beispielprogramm kopieren, aber nichts aus der Dokumentation!
Teilnehmerfrage Wie findet man Methoden?
Ein Kursteilnehmer fragte, wie man Methoden findet, deren Namen man nicht kennt.
Wenn jemand beispielsweise Zufallszahlen mit Java berechnen will, aber die Methode »random« nicht kennt, kann er [Java Zufallszahl] in eine Suchmaschine eingeben, um zu erfahren, wie Zufallszahlen mit Java berechnet werden können.
Übungsfragen
⚠ Da die Auswahl an einfach aufrufbaren Methoden an dieser Stelle des Kurses noch nicht so groß ist, werden in den Übungsaufgaben dieser und den folgenden Lektionen einige Methoden als Beispiele verwendet, deren Sinn (Nutzen) nicht immer gut erkennbar ist. Der Leser sollte sich an dieser Stelle noch keine Gedanken darüber machen, wofür diese Methoden gut sind ! Es geht zunächst nur darum, an (beliebigen) Beispielen zu erlernen, wie Methoden aufgerufen werden.
(Da es nicht möglich war, einfache und offensichtlich nützliche Methoden zu finden, haben wir hier der Einfachheit den Vorrang vor der erkennbaren Nützlichkeit gegeben. Die Methoden in dieser Übung sind also relativ einfach aufzurufen, aber ihr Nutzen ist derzeit oft nicht erkennbar.)
Im folgenden findet sich die Dokumentation einer Methode der Standardbibliothek.
- Dokumentation von »java.lang.Thread.activeCount()« (gekürzt, vereinfacht und übersetzt)
- Modul java.base
Paket java.lang
Klasse Thread
Methodenübersicht
public static int activeCount()
Ergibt die Anzahl der derzeit auf der Java -Maschine laufenden Programme (“threads”).
⚠ Denken Sie jetzt nicht weiter über die Bedeutung der „Anzahl laufender Programme“ nach! Die Methode »activeCount« dient hier nur als ein Beispiel, aber ihre genaue Bedeutung ist hier nicht wichtig.
- Aussprachehinweis
- thread θrɛd
? Lesen von Dokumentation
Welchen Typ hat ein Aufruf der oben dokumentierten Methode »activeCount()«?
Zu welcher Klasse gehört die oben dokumentierte Methode »activeCount()«?
? Selbständiges Lesen von Dokumentation
Welchen Typ hat ein Aufruf der Methode »java.lang.System.lineSeparator«?
? Selbständiges Lesen von Dokumentation (1)
Welchen Typ hat ein Aufruf der Methode »javax.swing.DebugGraphics.flashTime«?
Übungsaufgaben
Bei der Bearbeitung dieser Übungsaufgaben sollten die folgenden Hinweise beachtet werden:
- Kopieren Sie nichts aus der Dokumentation in Ihr Programm.
- Verändern Sie nichts am fest vorgegebenen Ausdruckrahmen (an den ersten drei Zeilen).
/ Selbständiges Schreiben von Programmen
Schreiben Sie ein Java -Programm, welches das Ergebnis eines Aufrufs der in einer voranstehenden Übungsfrage behandelten Methode »activeCount« ausgibt.
Wenn diese Aufgabe richtig gelöst wurde, dann sollte beim Übersetzen und beim Ablauf des Programms keine Fehlermeldung erscheinen, und das Programm sollte eine kleine natürliche Zahl (normalerweise »1«) ausgeben.
Main.javapublic final class Main
{ public static void main( final java.lang.String[] args )
{ java.lang.System.out.println
( java.lang.Math.random() ); }}java.lang.System.out0.5630878568955987
Tips
Um diese Aufgabe zu lösen, kann wie folgt vorgegangen werden:
- Das obenstehende Beispielprogramm »Main.java« kopieren.
- Den darin vorkommenden Methodennamen »java.lang.Math.random« ändern.
Der am Anfang des Aufrufs verwendete Methodenname setzt sich aus dem Namen der die Methode enthaltenden Klasse (zum Beispiel »java.lang.Math«) und dem eigentlichen Namen der Methode (zum Beispiel »random«) zusammen.
Reserveaufgaben
/ Selbständiges Arbeiten mit der Dokumentation
Hinweis für den Dozenten ► Diese Reserveaufgabe sollte erst nach der Nachbesprechung der vorherigen Übungsaufgabe bearbeitet werden.
Schreiben Sie ein Java -Programm, welches das Ergebnis eines Aufrufs der Methode »java.lang.System.nanoTime« ausgibt. (»long« ist ein Datentyp, welcher für diese Übungsaufgabe als »int« angesehen werden kann.)
- Aussprachehinweis
- nano time ˈnænoʊ taˑɪm
/ Selbständiges Arbeiten mit der Dokumentation (1)
Hinweis für den Dozenten ► Diese Reserveaufgabe sollte erst nach der Nachbesprechung der vorherigen Reserveaufgabe bearbeitet werden.
Schreiben Sie ein Java -Programm, welches das Ergebnis eines Aufrufs der Methode »java.lang.System.lineSeparator« ausgibt.
Übungsaufgaben (Fortsetzung)
/ Selbständiges Schreiben von Programmen (1)
Schreiben Sie ein Java -Programm, welches das Ergebnis einer Verkettung der folgenden drei Zeichenfolgen ausgibt.
1.) Die Zeichenfolge »abc«.
2.) Das Ergebnis eines Aufrufs der Methode »java.lang.System.lineSeparator«.
3.) Die Zeichenfolge »def«.
/ Ausgabe mehrerer Ergebnisse ⃗
Das folgende Programm gibt die Ergebnisse mehrerer Berechnungen in einer Zeile aus.
Main.javapublic final class Main
{ public static void main( final java.lang.String[] args )
{ java.lang.System.out.println
( "Masse = " +( 16./2 + 9 )+ " kg, Laenge = " +( 2 + 17./4 )+ " m." ); }}ProtokollMasse = 17.0 kg, Laenge = 6.25 m.
Überarbeiten Sie das Programm so, daß die folgende Ausgabe erscheint.
ProtokollMasse = 17.0 kg.
Laenge = 6.25 m.
Die Beispiele in diesem Kapitel *
In diesem Kapitel werden einige Methoden als Beispiele für Methoden vorgestellt. Die gewählten Beispiel wurden als Beispiel ausgewählt, weil sie relativ einfach verwendbar sind, aber nicht unbedigt, weil sie immer besonders nützlich sind. Deswegen wäre es in diesem Kapitel Zeitverschwendung, wenn man zu sehr versuchen würde, Details der hier als Beispiel vorgestellten Methoden zu erfahren und zu verstehen.
Es geht in diesem Kapitel nicht um die speziellen als Beispiel ausgewählten Methoden, sondern darum allgemein zu verstehen, wie Methoden verstanden und verwendet werden.