Interface ICalculator

package AstroOL;


/** Durchführung astrologischer Berechnungen. Dieses Interface legt die Schnittstellen
gängiger astrologischer Rechenaufgaben fest. Der Object Layer enthält derzeit drei
Implementierungen dieses Interfaces, von denen zwei auf der Swiss Ephemeris basieren
und die dritte eine niedriggenaue Ephemeride für den Offlinegebrauch darstellt. */
public interface ICalculator {


/** Angabe der URL eines Web-Service, der Horoskopberechnungen ausführen kann.
Es kann sich um ein Servlet handeln, ebenso gut aber auch um ein Perl-Skript oder
irgendeinen andere Art von Webdienst.
<p> Für die Implementierung des Interface ICalculator durch die Klasse Calculator
haben die Requestparameter des Services die folgende Bedeutung:
<ul>
<li><b>planets</b> Es soll eine Planetenberechnung durchgeführt werden
<li><b>houses</b> Es soll eine Häuserberechnung durchgeführt werden
<li><b>jd</b> Julianisches Datum des Zeitpunkts in ET
<li><b>lon</b> Geographische Länge, gezählt nach Osten
<li><b>lat</b> Geographische Breite, Norden zählt positiv.
</ul>
<p>
Das Ergebnis muss eine Antwort in <b><code>text/plain</code></b> sein (nicht HTML),
die aus mehreren Zeilen besteht. Die Zeilen beginnen mit den Schlüsselwörtern
<code>houses:</code>, <code>planets:</code>, <code>error:</code> oder <code>warning:</code>.
Hinter <code>houses:</code> und <code>planets:</code> sind die ekliptikalen Längen
der zwölf Häser bzw. der zehn Planeten im Dezimalformat als komma-separierte Liste
aufgeführt. Die Zeilen <code>error:</code> oder <code>warning:</code> enthalten
etwaige Warnungen oder Fehlermeldungen.
<p> Dieses Format ist natürlich für andere Implementierungen des Interface nicht
bindend. Es ist lediglich darauf zu achten, dass das Format, mit dem der Webservice seine
Antwort zurückliefert, zu dem Format passt, das von der Implementierung des Interface
entgegengenommen wird.
*/
  public void setServletURL(String servletURL);

/** Abfrage der URL, unter welcher die Planetenberechnung abrufbar ist */
  public String getServletURL( );



/** Berechnung der Planeten und Häuser. Eine Sammelmethode für den schnellen Zugriff
auf die üblichsten astrologischen Daten: Die ekliptikalen Planeten- und Hauspositionen.
@param jd_ut julianisches Datum in Weltzeit (nicht Ephemeridenzeit)
@param lon geographische Länge des Ortes (für Hausberechnungen)
@param lat geographische (nicht geozentrische) Breite des Ortes (für Hausberechnungen)
@param pl die Referenz auf ein Array von doppeltgenauen Gleitkommazahlen
mit mindestens zehn Elementen; die ersten zehn Elemente werden mit den
geozentrischen ekliptikalen Planetenpositionen in der Reihenfolge SO, MO, ME, VE, MA, JU, SA, UR, NE und PL
gefüllt.
@param h die Referenz auf ein Array von doppeltgenauen Gleitkommazahlen
mit mindestens dreizehn Elementen. Das erste Element (mit Index 0) bleibt leer. Das Element h[i]
wird für i = 1 bis 12 mit dem Wert der i. Hausspitze gefüllt. Die Wahl oder gar Wählbarkeit
des Häsersystems ist im Interface nicht festgelegt und stellt somit ein Implementierungsdetail dar.
@returns wahr, wenn die Berechnung erfolgreich ausgeführt werden konnte. Sonst falsch.
*/
  public boolean getPlanetsAndHouses( double jd_ut,
                                      double lon,
                                      double lat,
	                                  double[] pl,
                                      double[] h ) ;

/** Berechnung des geozentrischen Ortes und der Geschwindigkeit eines einzelnen Planeten zur
wahren Ekliptik des Datums.
@param jd_ut julianisches Datum in Weltzeit (nicht Ephemeridenzeit)
@param planet Nummer des Planeten. Es gilt die Reihenfolge SO, MO, ME, VE, MA, JU, SA, UR, NE und PL,
wobei SO die Nummer Null hat.
@param serr Fehler- oder Warnmeldung im Klartext.
Kann auch mehrere Meldungen, getrennt durch Zeilenvorschübe, enthalten.
@returns die Referenz auf ein Array von sechs doppeltgenauen Gleitkommazahlen. Bei Rückgabe
ist der Array in dieser Reihenfolge mit folgenden Werten gefüllt:
<ul>
<li> Ekliptikale Länge in Grad
<li> Ekliptikale Breite in Grad
<li> Abstand vom Erdmittelpunkt in Astronomischen Einheiten (AU)
<li> Momentane Änderung der Länge in Grad pro Tag
<li> Momentane Änderung der Breite in Grad pro Tag
<li> Momentane Änderung des Abstands in AU pro Tag
</ul>
*/
  public double[] getPlanet( double jd_ut,
                             int planet,
                             StringBuffer serr) ;


/** Berechnung einer einzelnen Häserspitze.
@param jd_ut julianisches Datum in Weltzeit (nicht Ephemeridenzeit)
@param lon geographische Länge des Ortes (für Hausberechnungen)
@param lat geographische (nicht geozentrische) Breite des Ortes (für Hausberechnungen)
@param die zu berechnende Häuserspitze. Das Interface schreibt nur vor, daß die
ganzzahligen Werte 1 bis 12 den Spitzen der Häser 1 bis 12 entsprechen. Die implementierenden
Klassen Calculator und LowPrecCalculator interpretieren Zwischenwerte als mundane Position.
@returns die ekliptikale Länge der Häserspitze. */
  public double getHouse( double jd_ut,
                          double lon,
                          double lat,
                          double houseNumber,
                          StringBuffer serr) ;

}