com.vwp.vuapi
Class VUInterface

java.lang.Object
  com.vwp.vuapi.VUInterface

public abstract class VUInterface
extends Object

The class VUConnection is the interface from an Java application to the Virtual Universe, it is the main entry point for the API. To access the functionality of the VU API the only class that is allowed to inherit from this one has to be used: VUConnection. It is available within the MainWin.jar archive that is required and has to be added to the classpath to access the API.

Field Summary

String	IP
int	Mode
int	Port
static int	VU_API_MODE_3D_VIEW Mode flags for the API: open a 3D view
static int	VU_API_MODE_DAEMON Mode flags for the API: run completely in background
static int	VU_ERROR_CLIENT_VERSION The clients version number and the one that is required by the server don't fit together, it should be updated to the latest MainWin.jar
static int	VU_ERROR_IO_ERROR Return code: IO operation failed
static int	VU_ERROR_NO_GALAXY_AUTH Return code: login-error; the user has no privilege to enter that galaxy
static int	VU_ERROR_NO_PLANET_AUTH Return code: login-error; the user has no privilege to enter that planet
static int	VU_ERROR_NO_PRIVILEGE_FOR_OPERATION The user doesn't has enough privileges for the operation
static int	VU_ERROR_NO_SOL_AUTH Return code: login-error; the user has no privilege to enter that solar system
static int	VU_ERROR_NO_UNI_AUTH Return code: login-error; the user has no privilege to enter that universe
static int	VU_ERROR_PASSWORD Return code: login-error; the given password is wrong
static int	VU_ERROR_PROTOCOL_IO_ERROR Return code: IO operation failure in protocol stack
static int	VU_ERROR_UNKNOWNHOST Return code: socket-error, the specified hos is not known
static int	VU_ERROR_USER_BANNED Return code: login-error; the user is banned
static int	VU_ERROR_USERNAME Return code: the username doesn't exists or the user is already logged in
static int	VU_ERROR_WORLD_ID Return code: login-error; the world doesn't exists
static int	VU_ERROR_WORLD_NA Return code: login-error; the world is not available
static int	VU_ERROR_WORLD_RESTRICTED Return code: the user has no privilege to enter the restrcted world
static int	VU_OK Return code: everything is OK, operation performed successfully
static int	VU_USER_VISIBILITY_BRB User visibility flag: user is currently away
static int	VU_USER_VISIBILITY_INVISIBLE User visibility flag: user is invisible
static int	VU_USER_VISIBILITY_IRC User visibility flag: user is connected from IRC

Constructor Summary

VUInterface(String IP, int Port, int Mode)
The main constructor for the VU API interface; although if IP and port number are required as parameter here it doesn't opens the connection to a server, that has be done with an explicit call to connect()

Method Summary

abstract void	addCommunicationListener(VUCommunicationListener cListener) Adds a listener to watch the communication of users within a world
abstract void	addObjectListener(VUObjectListener oListener) Adds a listener to watch changes in the list of objects
abstract void	addPositionListener(VUPositionListener pListener) Adds a listener to watch the changes in the positions of users within a world
abstract void	addUserListener(VUUserListener uListener) Adds a listener to watch changes in the list of users within a world
abstract void	addWorldListener(VUWorldListener wListener) Adds a listener to watch changes in the list of available worlds
abstract int	buildObject(VUObjectInfo obj) This method has to be called to build a new object or to change a existing one.
abstract void	close() Closes the connection to the Virtual Universe server and deinitializes everything
abstract int	connect(String UserName, String Password) Connects with the server that was specified using the IP and port number given during construction of this object.
abstract int	enterWorld(String Name) Tries to log into a world after a successful connect() to a server.
abstract String	getAPIVersion() Get the APIs version number
abstract String	getClientVersion() Retrieve the client version number
abstract void	getPosition(javax.vecmath.Vector3d pos, javax.vecmath.Point3f rot) This version returns the current position and orientation of the robot using the both object handed over as parameter.
abstract void	modifyAudiotrack(NonSpatialSound audiotrack) This method modifies an existing and already replaying non-spatial sound conform to the values that are handed over with the parameter.
abstract javax.media.j3d.Canvas3D	open3DView() If the opject was created in mode VU_API_MODE_3D_VIEW, this method can be used to create and open the 3D View.
abstract void	queryObjects(double x, double y, double z, double areaWidth) Query for the objects that are available within a specific area.
abstract void	sendChatText(String text) Sends a public chat text to te world currently logged in
abstract void	setPosition(javax.vecmath.Vector3d pos, float angleY, float eyeHeight, String avatarURL) Change the position of a robot that was connected to a server and logged into a world succesfully.
abstract NonSpatialSound	startAudiotrack(String FileURL, double x, double y, double z, double radius, int volume) The replaying of a non-spatial sound is started when the application has build-privileges.
abstract void	stopAudiotrack(NonSpatialSound audiotrack) This method stops an existing and possibly replaying non-spatial sound.
abstract boolean	walkToPosition(javax.vecmath.Vector3d pos) Tries to change the position of a robot that was connected to a server and logged into a world succesfully.

Methods inherited from class java.lang.Object

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

Field Detail

VU_OK

public static final int VU_OK

Return code: everything is OK, operation performed successfully

See Also:

Constant Field Values

VU_ERROR_UNKNOWNHOST

public static final int VU_ERROR_UNKNOWNHOST

Return code: socket-error, the specified hos is not known

See Also:

Constant Field Values

VU_ERROR_IO_ERROR

public static final int VU_ERROR_IO_ERROR

Return code: IO operation failed

See Also:

Constant Field Values

VU_ERROR_PROTOCOL_IO_ERROR

public static final int VU_ERROR_PROTOCOL_IO_ERROR

Return code: IO operation failure in protocol stack

See Also:

Constant Field Values

VU_ERROR_USERNAME

public static final int VU_ERROR_USERNAME

Return code: the username doesn't exists or the user is already logged in

See Also:

Constant Field Values

VU_ERROR_PASSWORD

public static final int VU_ERROR_PASSWORD

Return code: login-error; the given password is wrong

See Also:

Constant Field Values

VU_ERROR_USER_BANNED

public static final int VU_ERROR_USER_BANNED

Return code: login-error; the user is banned

See Also:

Constant Field Values

VU_ERROR_WORLD_ID

public static final int VU_ERROR_WORLD_ID

Return code: login-error; the world doesn't exists

See Also:

Constant Field Values

VU_ERROR_NO_UNI_AUTH

public static final int VU_ERROR_NO_UNI_AUTH

Return code: login-error; the user has no privilege to enter that universe

See Also:

Constant Field Values

VU_ERROR_NO_GALAXY_AUTH

public static final int VU_ERROR_NO_GALAXY_AUTH

Return code: login-error; the user has no privilege to enter that galaxy

See Also:

Constant Field Values

VU_ERROR_NO_SOL_AUTH

public static final int VU_ERROR_NO_SOL_AUTH

Return code: login-error; the user has no privilege to enter that solar system

See Also:

Constant Field Values

VU_ERROR_NO_PLANET_AUTH

public static final int VU_ERROR_NO_PLANET_AUTH

Return code: login-error; the user has no privilege to enter that planet

See Also:

Constant Field Values

VU_ERROR_WORLD_RESTRICTED

public static final int VU_ERROR_WORLD_RESTRICTED

Return code: the user has no privilege to enter the restrcted world

See Also:

Constant Field Values

VU_ERROR_WORLD_NA

public static final int VU_ERROR_WORLD_NA

Return code: login-error; the world is not available

See Also:

Constant Field Values

VU_ERROR_CLIENT_VERSION

public static final int VU_ERROR_CLIENT_VERSION

The clients version number and the one that is required by the server don't fit together, it should be updated to the latest MainWin.jar

See Also:

Constant Field Values

VU_ERROR_NO_PRIVILEGE_FOR_OPERATION

public static final int VU_ERROR_NO_PRIVILEGE_FOR_OPERATION

The user doesn't has enough privileges for the operation

See Also:

Constant Field Values

VU_API_MODE_DAEMON

public static final int VU_API_MODE_DAEMON

Mode flags for the API: run completely in background

See Also:

Constant Field Values

VU_API_MODE_3D_VIEW

public static final int VU_API_MODE_3D_VIEW

Mode flags for the API: open a 3D view

See Also:

Constant Field Values

VU_USER_VISIBILITY_BRB

public static final int VU_USER_VISIBILITY_BRB

User visibility flag: user is currently away

See Also:

Constant Field Values

VU_USER_VISIBILITY_INVISIBLE

public static final int VU_USER_VISIBILITY_INVISIBLE

User visibility flag: user is invisible

See Also:

Constant Field Values

VU_USER_VISIBILITY_IRC

public static final int VU_USER_VISIBILITY_IRC

User visibility flag: user is connected from IRC

See Also:

Constant Field Values

IP

public String IP

Port

public int Port

Mode

public int Mode

Constructor Detail

VUInterface

public VUInterface(String IP,
                   int Port,
                   int Mode)

The main constructor for the VU API interface; although if IP and port number are required as parameter here it doesn't opens the connection to a server, that has be done with an explicit call to connect()

Parameters:

IP - the IP of the server to connect with

Port - the port number of the server

Mode - VU_API_MODE_xxx flags that specify how the application has to be executed

Method Detail

close

public abstract void close()

Closes the connection to the Virtual Universe server and deinitializes everything

open3DView

public abstract javax.media.j3d.Canvas3D open3DView()

If the opject was created in mode VU_API_MODE_3D_VIEW, this method can be used to create and open the 3D View. It has to be called directly after instantiation of this object.

Returns:

the 3D View object or null if an error occured

connect

public abstract int connect(String UserName,
                            String Password)

Connects with the server that was specified using the IP and port number given during construction of this object. Connecting with a server is possible only using a registerd username, unknown lifeforms can't be robots.

Parameters:

UserName - the registerd username the robot has to use

Password - the password for that user

Returns:

an VU_ERROR_xxx error code that specifies an possibly occured error or VU_OK otherwise

enterWorld

public abstract int enterWorld(String Name)

Tries to log into a world after a successful connect() to a server. This method should be called only after the name of the world appeared. That fact can be tested using a VUWorldListener. Logging into a world is done successfully and completely only when the own username appeared in that world. Checking if a user entered a world can be done using a VUUserListener or a VUCommunicationListener.
This method has to be called again with different parameters to leave one world and to enter the next one.

Parameters:

Name - the name of the world that has to be entered

Returns:

an VU_ERROR_xxx errorcode that specifies an possibly occured error or VU_OK otherwise

setPosition

public abstract void setPosition(javax.vecmath.Vector3d pos,
                                 float angleY,
                                 float eyeHeight,
                                 String avatarURL)

Change the position of a robot that was connected to a server and logged into a world succesfully.

Parameters:

pos - the position of the robot in unit m

angleY - the orientation robot in unit degrees

eyeHeight - the height of the robots view point (ist eyes) from the ground

avatarURL - the url of the avatars 3D-model that has to be shown as the robots appearance. If null is handed over here for every call of setPosition() the robot will be invisible. If a avatar-model has to be specified to make the robot visible as some kind of person, that has to be done only once after logging into a world. Otherwise the avatar-URL infomation is sent for every call of setPosition() what causes high traffic and slow movements of the robot.
The avatar-model can be changed by calling this method using a URL to a different 3D-model.

walkToPosition

public abstract boolean walkToPosition(javax.vecmath.Vector3d pos)

Tries to change the position of a robot that was connected to a server and logged into a world succesfully. This operation will be performed succesfully only if the defined walking step doesn't causes a collision with an object and doesn't requires a step in Y-direction that is bigger than a person could walk. Here it has to be ensured that the distance between two walking steps or between the last call to setPosition() and walkToPosition() is not too big.
Before the first call of this method a robot has to be placed within a world using setPosition(), this method has to be used also for changes in the orientation and the eye height of the robot.

Parameters:

pos - the position the robot has to walk to (in unit m)

Returns:

true if the walking step could be done, or false in case of a collision

getPosition

public abstract void getPosition(javax.vecmath.Vector3d pos,
                                 javax.vecmath.Point3f rot)

This version returns the current position and orientation of the robot using the both object handed over as parameter. If walkToPosition() is used these positions can differ from the set values due to the terrain following. If the robot climbed a height difference the Y-coordinate is changed automatically.

Parameters:

pos - the current poisiton is returned using this object

rot - with this object the robots oritenation is given

buildObject

public abstract int buildObject(VUObjectInfo obj)

This method has to be called to build a new object or to change a existing one. The object that has to be build is defined by the parameter that is a VUObjectInfo subclass of the appropriate type.
To modify an existing object, the VUObjectInfo delivered by a VUObjectListener has to be used. Here the desired parameters and values have to be changed before calling buildObject(). Comparing to that putting a new object into a world requires an object type that inherits from VUObjectInfo as parameter. The difference between both is the ID. An existing object owns an valid ID while creating a new VUObjectInfo is done without any ID, it is initialized to a default value that signals the API that this one is a new object.

Parameters:

obj - the object that has to be build

Returns:

an VU_ERROR_xxx error code if something failed or 0 otherwise

getClientVersion

public abstract String getClientVersion()

Retrieve the client version number

Returns:

the clients version number

getAPIVersion

public abstract String getAPIVersion()

Get the APIs version number

Returns:

the version number of the API

sendChatText

public abstract void sendChatText(String text)

Sends a public chat text to te world currently logged in

Parameters:

text - the text that has to be send

queryObjects

public abstract void queryObjects(double x,
                                  double y,
                                  double z,
                                  double areaWidth)

Query for the objects that are available within a specific area. The result of that operation can be read using a VUObjectListener

Parameters:

x - east-west coordinate of the center of the square that has to be queried

y - height coordinate of the center of the square that has to be queried

z - north-south coordinate of the center of the square that has to be queried for objects

areaWidth - the length of the squares edge that has to be queried

Throws:

IllegalArgumentException - when this method is called and no VUObjectListener is specified to receive the results

startAudiotrack

public abstract NonSpatialSound startAudiotrack(String FileURL,
                                                double x,
                                                double y,
                                                double z,
                                                double radius,
                                                int volume)

The replaying of a non-spatial sound is started when the application has build-privileges. This sound is replayed for all client browsers that are connected to the same world and are located near the position of this sound source. It influences only these clients, there doesn't changes anything for the API that uses this method.

Parameters:

FileURL - the URL of the soundfile that has to be downloaded, please refer to the documentation about the "audiotrack" object command for a list of supported audio formats

x - the x position of the sound source

y - the y position of the sound source

z - the z position of the sound source

radius - the radius of the area in meters that is influenced by this sound, the volume of the sound output decreases with an increasing distance to its center coordinates and is 0 at a distance of "radius" from the sound sources coordinates; allowed values are in range of 1..100 m

volume - the volume of the sound at the center coordinates in percent, here a range of 0..100% is allowed

Returns:

a NonSpatialSound object that can be used to modify or stop this sound or null if an error occured

Throws:

IllegalArgumentException - if parameters with illegal values have been handed over

modifyAudiotrack

public abstract void modifyAudiotrack(NonSpatialSound audiotrack)

This method modifies an existing and already replaying non-spatial sound conform to the values that are handed over with the parameter.

Parameters:

audiotrack - a NonSpatialSound object that contains the new parameters of a sound; here the members x, y, z, radius and volume can be modified before calling this method, all other values are ignored

stopAudiotrack

public abstract void stopAudiotrack(NonSpatialSound audiotrack)

This method stops an existing and possibly replaying non-spatial sound.

Parameters:

audiotrack - a NonSpatialSound object that identifies the sound that has to be stopped

addObjectListener

public abstract void addObjectListener(VUObjectListener oListener)

Adds a listener to watch changes in the list of objects

Parameters:

oListener - a VUObjectListener object used to watch the world object changes

addWorldListener

public abstract void addWorldListener(VUWorldListener wListener)

Adds a listener to watch changes in the list of available worlds

Parameters:

wListener - a VUWorldListener object used to watch the world changes

addUserListener

public abstract void addUserListener(VUUserListener uListener)

Adds a listener to watch changes in the list of users within a world

Parameters:

uListener - a VUUserListener object used to watch the user changes

addCommunicationListener

public abstract void addCommunicationListener(VUCommunicationListener cListener)

Adds a listener to watch the communication of users within a world

Parameters:

cListener - a VUCommunicationListener object used to watch the communication

addPositionListener

public abstract void addPositionListener(VUPositionListener pListener)

Adds a listener to watch the changes in the positions of users within a world

Parameters:

pListener - a VUPositionListener object used to watch the position changes