greenfoot
Class UserInfo

java.lang.Object
  greenfoot.UserInfo

public class UserInfo
extends Object

Die Klasse UserInfo kann zum permanenten Speichern von Daten auf einem Server und zum Teilen dieser Daten mit anderen Nutzern benutzt werden, falls das Szenario auf der offiziellen Greenfoot Webseite ausgeführt wird. Beispielsweise können mit dieser Klasse High-Score Tabellen implementiert werden.

Der Speicher kann nur von registrierten Mitgliedern benutzt werden. Deshalb muss man immer zunächst mit UserInfo.isStorageAvailable() prüfen, ob der Speicher genutzt werden kann.

Zur Verdeutlichung hier eine mögliche Implementation eines Highscores:

    if (UserInfo.isStorageAvailable()) {

        UserInfo myInfo = UserInfo.getMyInfo();

        if (newScore > myInfo.getScore()) {

            myInfo.setScore(newScore);

            myInfo.store();  // Speichern auf dem Server

        }

    }

Zum Empfangen von Benutzerdaten stehen verschiedene Methoden zur Verfügung, wie zum Beispiel getMyInfo(), die Informationen über den aktuellen Benutzer liefert, getTop(10), die die Besten zurückliefert, und getNearby(10), welche vergleichbare Nutzer zurückliefert.

Als Speicherplatz stehen für jeden Benutzer ein Spielstand, zehn zusätzliche Integer und fünf Strings (maximal 50 Zeichen lang) zur freien Verfügung. Desweiteren kann der Benutzername und das Benutzerbild von den Benutzerdaten empfangen werden.

Zum offline Testen kann der Benutzername in den Einstellungen gesetzt werden (Strg-Shift-P / Cmd-Shift-P). Dadurch können während der Entwicklung verschiedene Benutzer simuliert werden. Sobald die Applikation auf der offiziellen Greenfoot Webseite ausgeführt wird, wird der Benutzername zum Einloggen auf der Seite benutzt.

Version:

2.4

Author:

Dennis Nolte

Field Summary

static int	NUM_INTS Die Anzahl der speicherbaren Integer Zahlen.
static int	NUM_STRINGS Die Anzahl der speicherbaren Strings.
static int	STRING_LENGTH_LIMIT Die maximale Länge eines zu speichernden Strings.

Constructor Summary

UserInfo()

Method Summary

int	getInt(int index) Gibt den Integer am entsprechenden Index (0 bis NUM_INTS -1, inklusiv) zurück.
static UserInfo	getMyInfo() Gibt die gespeicherten Daten für den Benutzer zurück.
static List	getNearby(int maxAmount) Gibt eine sortierte Liste mit UserInfo Objekten zurück, welche den aktuellen Benutzer umgeben.
int	getRank() Gibt den aktuellen Rang des Benutzers für dieses Szenario zurück.
int	getScore() Gibt den Spielstand des Benutzers.
String	getString(int index) Gibt den String am entsprechenden Index (0 bis NUM_STRINGS -1, inklusiv) zurück.
static List	getTop(int maxAmount) Gibt eine sortierte Liste mit UserInfo Objekten zurück, welche die Benutzer mit der besten Score beschreiben.
GreenfootImage	getUserImage() Gibt das Benutzerbild zurück.
String	getUserName() Gibt den Benutzernamen des zum Speicher gehörenden Benutzers an.
static boolean	isStorageAvailable() Prüft, ob Speicher verfügbar ist.
void	setInt(int index, int value) Setzt den Wert value am entsprechenden Index (0 bis NUM_INTS -1, inklusiv).
void	setScore(int score) Setzt den Spielstand des Benutzers.
void	setString(int index, String value) Setzt den String value am entsprechenden Index (0 bis NUM_STRINGS -1, inklusiv).
boolean	store() Speichert die Daten auf dem Server.

Methods inherited from class

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

NUM_INTS

public static final int NUM_INTS

Die Anzahl der speicherbaren Integer Zahlen.

See Also:

Field values, Constant Field Values

NUM_STRINGS

public static final int NUM_STRINGS

Die Anzahl der speicherbaren Strings.

See Also:

Field values, Constant Field Values

STRING_LENGTH_LIMIT

public static final int STRING_LENGTH_LIMIT

Die maximale Länge eines zu speichernden Strings.

See Also:

Field values, Constant Field Values

Constructor Detail

UserInfo

public UserInfo()

Method Detail

getInt

public int getInt(int index)

Gibt den Integer am entsprechenden Index (0 bis NUM_INTS -1, inklusiv) zurück.

Der Standardwert ist eine Null.

getMyInfo

public static UserInfo getMyInfo()

Gibt die gespeicherten Daten für den Benutzer zurück. Gibt null zurück, falls:

• ein Problem beim Lesen der lokalen Speicherdatei ("storage.csv") vorliegt (für lokale Szenarien), oder
• das Szenario als Standalone Anwendung oder nicht auf der offiziellen Greenfoot Webseite ausgeführt wird, oder
• ein Problem mit der Serverkommunikation vorliegt (für Szenarien auf greenfoot.org), oder
• der Benutzer nicht eingeloggt ist (für Szenarien auf greenfoot.org)

Da der letzte Fall regelmäßig vorkommt, sollte das Szenario den Rückgabewert null abfangen können.

Returns:

Die Benutzerdaten, oder null falls ein Problem vorliegt.

getNearby

public static List getNearby(int maxAmount)

Gibt eine sortierte Liste mit UserInfo Objekten zurück, welche den aktuellen Benutzer umgeben.

Für jeden Benutzer wird dabei ein UserInfo Objekt zurückgegeben. Die Liste ist nach dem Rückgabewert von getScore() absteigend sortiert. Der Parameter bietet die Möglichkeit die maximale Länge der zurückgegebenen Liste zu bestimmen. Falls euer Szenario viele Benutzerdaten gespeichert hat, kann es sowohl zeitintensiv als auch trafficintensiv sein, alle Benutzerdaten zu empfangen. Meistens werden außerdem weniger Benutzerdaten benötigt.

Die UserInfo Objekte beschreiben die Benutzer, die den aktuellen Benutzer umgeben, sprich relativ vergleichbar sind. Dabei wird der aktuelle Benutzer in der Liste mit eingeschlossen sein. Der aktuelle Benutzer ist jedoch nicht zwingend mittig in der Liste. Auch wenn die Chance sehr hoch ist, wird zum Beispiel für den Zweitbesten mit dem Aufruf getNearby(7) eine Liste zurückgeliefert, in der das UserInfo Objekt des aktuellen Benutzers nicht mittig, sondern relativ weit vorne liegt.

Falls ihr die Highscore der vergleichbaren Benutzer anzeigen lassen wollt, könnt ihr zum Beispiel erst die Daten mit setScore(score) und store() speichern und mittels getNearby(10) den Punktestand der zehn vergleichbarsten Benutzer erfragen.

Gibt null zurück, falls:

• ein Problem beim Lesen der lokalen Speicherdatei ("storage.csv") vorliegt (für lokale Szenarien), oder
• das Szenario als Standalone Anwendung oder nicht auf der offiziellen Greenfoot Webseite ausgeführt wird, oder
• ein Problem mit der Serverkommunikation vorliegt (für Szenarien auf greenfoot.org), oder
• der Benutzer nicht eingeloggt ist (für Szenarien auf greenfoot.org)

Das Programm sollte stets den Rückgabewert null verarbeiten können.

Parameters:

maxAmount - Die maximale Anzahl an zu empfangenen UserInfo Objekten. Das Übergeben von 0 oder einer negativen Zahl liefert sämtliche Benutzerdaten zurück, beachte allerdings den Hinweis weiter oben.

Returns:

Eine Liste mit UserInfo Objekten oder null, falls ein Problem vorliegt.

getRank

public int getRank()

Gibt den aktuellen Rang des Benutzers für dieses Szenario zurück.

Der Benutzer mit dem besten Spielstand bekommt eine 1 zurück, der mit dem zweitbesten eine 2, und so weiter. Der Rank ist nicht eindeutig, da jeder, der denselben Spielstand hat, denselben Rang hat. Um den Rang zu finden, werden die Spielstände in absteigender Reihenfolge sortiert (der Beste oben). Falls in deinem Szenario die Spielstände umgekehrt angezeigt werden sollen (der Schlechteste oben) kannst du negative Zahlen benutzen.

Falls der Rang nicht abgefragt werden kann (z.B. weil der Spielstand noch nicht gespeichert wurde), wird -1 zurückgegeben.

getScore

public int getScore()

Gibt den Spielstand des Benutzers. Standardmäßig ist dieser eine Null.

getString

public String getString(int index)

Gibt den String am entsprechenden Index (0 bis NUM_STRINGS -1, inklusiv) zurück.

Der Standardwert ist ein leerer String.

getTop

public static List getTop(int maxAmount)

Gibt eine sortierte Liste mit UserInfo Objekten zurück, welche die Benutzer mit der besten Score beschreiben.

Für jeden Benutzer wird dabei ein UserInfo Objekt zurückgegeben. Die Liste ist nach dem Rückgabewert von getScore() absteigend sortiert. Der Parameter bietet die Möglichkeit die maximale Länge der zurückgegebenen Liste zu bestimmen. Falls euer Szenario viele Benutzerdaten gespeichert hat, kann es sowohl zeitintensiv als auch trafficintensiv sein, alle Benutzerdaten zu empfangen. Meistens werden außerdem weniger Benutzerdaten benötigt.

Falls ihr den Highscore der besten Benutzer anzeigen lassen wollt, könnt ihr zum Beispiel erst die Daten mit setScore(score) und store() speichern und mittels getTop(10) die zehn besten Benutzer erfragen.

Gibt null zurück, falls:

• ein Problem beim Lesen der lokalen Speicherdatei ("storage.csv") vorliegt (für lokale Szenarien), oder
• das Szenario als Standalone Anwendung oder nicht auf der offiziellen Greenfoot Webseite ausgeführt wird, oder
• ein Problem mit der Serverkommunikation vorliegt (für Szenarien auf greenfoot.org), oder
• der Benutzer nicht eingeloggt ist (für Szenarien auf greenfoot.org)

Das Programm sollte stets den Rückgabewert null verarbeiten können.

Parameters:

maxAmount - Die maximale Anzahl an zu empfangenen UserInfo Objekten. Das Übergeben von 0 oder einer negativen Zahl liefert sämtliche Benutzerdaten zurück, beachte allerdings den Hinweis weiter oben.

Returns:

Eine Liste mit UserInfo Objekten oder null, falls ein Problem vorliegt.

getUserImage

public GreenfootImage getUserImage()

Gibt das Benutzerbild zurück. Dieses ist 50x50 Pixel groß.

Auf der offiziellen Greenfoot Webseite ist dies das Profilbild des Benutzers. Falls das Szenario lokal ausgeführt wird, oder kein Profilbild verfügbar ist, wird ein Dummy-Bild zurückgegeben, auf welchem der Name des Benutzers gezeichnet ist.

Returns:

Ein 50x50 Pixel großes GreenfootImage

getUserName

public String getUserName()

Gibt den Benutzernamen des zum Speicher gehörenden Benutzers an.

isStorageAvailable

public static boolean isStorageAvailable()

Prüft, ob Speicher verfügbar ist.

Speicher ist nicht verfügbar falls die Anwendung als Applet außerhalb der offiziellen Greenfoot Webseite oder als Standalone-Anwendung ausgeführt wird, oder falls der Benutzer sich nicht auf der Webseite eingeloggt hat. Da der letzte Fall sehr häufig vorkommt, solltest du immer zunächst mit Hilfe dieser Methode prüfen, ob Speicher verfügbar ist, bevor du Speicheroperationen verwendest. Falls diese Methode false zurückliefert, sollte das Szenario ohne Speichernutzung fortfahren.

setInt

public void setInt(int index,
                   int value)

Setzt den Wert value am entsprechenden Index (0 bis NUM_INTS -1, inklusiv).

Zum permanenten Speichern muss später die Methode store() aufgerufen werden.

setScore

public void setScore(int score)

Setzt den Spielstand des Benutzers.

Beachte, dass hiermit jeglicher Wert gespeichert wird. Falls du nur den besten Wert speichern möchtest, musst du dies vorher abfragen:

    if (latestScore > userData.getScore())

    {

        userData.setScore(latestScore);

    }

Andernfalls wird jeder vorherige Wert überschrieben.

Zum permanenten Speichern muss später die Methode store() aufgerufen werden.

setString

public void setString(int index,
                      String value)

Setzt den String value am entsprechenden Index (0 bis NUM_STRINGS -1, inklusiv). Das Übergeben von null als Wert erzeugt einen leeren String. Der übergebene String value darf maximal STRING_LENGTH_LIMIT Zeichen lang sein.

Zum permanenten Speichern muss später die Methode store() aufgerufen werden.

store

public boolean store()

Speichert die Daten auf dem Server.

Gespeichert werden können nur Daten für den aktuellen Benutzer (also Daten, die durch getMyData() empfangen worden sind). Das Speichern von Daten für fremde Benutzer wird nicht funktionieren.

Returns:

true, falls erfolgreich gespeichert wurde, false, falls ein Problem vorliegt