Component:Java bindings

**This page describes a component of XMMS2.**

The Summary section will be used as a basis for package descriptions, so please make sure that the text is suited for that. The contents of this page will be gathered automatically by a script. It is important that the Summary section is kept.

Summary =======

Java bindings for the client library.

Big Mark

The javabindings were temporary removed from xmms2 due to problems with waf. They will come back as soon as we get up with waf/swig, get genIPC working with java or the buildsystem changes again ;). For now the javabindings are in x4x in a cvs module.

See 1

Prerequisites

Since DrDolittle Xmms2 ships some bindings to the language Java. To get those bindings on your machine you need some prerequisites met and installed:

• Installed JDK (Java development kit a jre is not enough!) (>=1.4.2): no matter if blackdown or sun, both are tested, Java5 works too. Don't know gcj but afaik this works too. java, javac and jar have to be in path.
• Installed SWIG (2) (>=1.3.25): swig has to be in path.
• JAVA_HOME must be set, otherwise scons skips installation of the javabindings for now.

Usage

After you have them installed you are either a developer and want to use them to develop something nifty or you are a user and have no idea which client to choose now.

If you are a user go to http://x4x.sourceforge.net and grab X4X, atm the only java-client. Follow the X4X installationintructions and hope everything works. Else visit #x4x on 3.

If you are a developer you can check the sourcecode swig and we generated in src/clients/lib/java. You have some choices of using the javabindings now, but before everything build doxygen and javadoc docu, you will need it.

Build the doxygen docs by simply running

doxygen

in the main directory (or simply look at 4) and build javadoc by running

javadoc -d doc/html/javadoc src/clients/lib/java/src/org/xmms2/*java src/clients/lib/java/src/org/xmms2/xmms2bindings/*java

That command will fail if you didn't generate the things in src/clients/lib/java/src/org/xmms2/xmms2bindings/ first using swig and scons

After that you have two main choices:

1. (deprecated) Use the C-API style code: Your mainclass to use is org.xmms2.xmms2bindings.Xmmsclient. For documentation on the various functions check the c pendants, everything works exactly the same. Besides that option you have to choose if you use org.xmms2.JMain as your mainloop (which is recommended) or build your own (which is annoying, so use JMain!). I only explain the JMain-way a bit here, for ideas on building an own loop check our loop. To use JMain you have to implement CallbacksListener or extend CallbacksAdapter (you can only use one, not two, not three, only one). Just instantiate a JMain with your CallbacksListener as argument and use org.xmms2.xmms2bindings.Xmmsclient to work with xmms2. But be warned: NEVER USE WAIT() THEN. When you use a Mainloop, no matter which, you enter the async mode, so use result_notifier() instead of wait() then.
2. (recommended) Use the nice and nifty new things I wrote today afternoon (They are DrDolittle+WIP). Your classes are org.xmms2.Xmms2, org.xmms2.Xmms2Listener/-Adapter, org.xmms2.Xmms2Event and org.xmms2.Title. It works without all the org.xmms2.xmms2bindings.* things since they are not nice to read. Since you built the doc as mentionend above just check the nice examples that are in org.xmms2.Xmms2. In short words do the following things:

Async way

Xmms2 bleh = Xmms2.getInstance("YourClientsName"); bleh.connect(); bleh.addXmms2Listener(new Xmms2Adapter(){  ..... }); bleh.play(); bleh.playlistListAsync(); bleh.spinDown();

connect()/addListener()/spinDown() are quite important so be careful using them. You get every kind of data (no matter you wanted it or the server broadcastet it) via the Listeners methods. When someone is on the way of using that new name please contact dangertools on #x4x or #xmms2 since this second API isn't tested quite much.

This new and easy API follows more or less the MVC-pattern (if you ask yourself now "What the hell is a pattern?", go and buy a book, e.g. 5. It hurts your purse but will improve your skillz).

The model in this case is the class implementing org.xmms2.Xmms2Listener, the controller is the class using org.xmms2.Xmms2 and the view is whatever UI-framework you choose ;)

Sync way

Since I think that there are still some needs of calling things sync but with blocking I implemented some more methods that work on a second connection but totally sync. That means that the methods return directly to the caller after they have finished. All functions which return some useful data are now available as functionNameAsync() and a functionNameSync() where the *Async() methods return to all connected listeners whereas the *Sync() methods return directly and only to the caller. To have that working in a simple way org.xmms2.Xmms2Backoffice now has two connections, named clientName1 and clientName2. The first one is used for the async things, the second one only for the sync methods. Here some quick example:

Xmms2 bleh = Xmms2.getInstance("YourClientsName"); bleh.connect(); Map configs = bleh.configvalListSync(); /* Do some funny things with the configs */ Title t = bleh.mlibGetTitleSync(currentIDSync()); System.out.println(t); bleh.spinDown();

But be careful when doing such things with mlibSelectSync() e.g. which could probably return a huge list and therefor take some time.

For some more examples have a look at the xmms2-tutorial project which explains step by step almost all possible api uses.

Latest news/changes

20070305 The javabindings were temporary removed from xmms2 due to problems with waf. They will come back as soon as we get up with waf/swig, get genIPC working with java or the buildsystem changes again ;). For now the javabindings are in x4x in a cvs module.

20070103 Right, latest news are quite old already, forgot to add them here. The second API will be removed from the main xmms2 tree, seems like I have to develop them somewhere else. Atm not waf problems have to be fixed, then some updates will hit -devel. Updates means collections-api, some slight but unmentionable changes and removing the the second api.

20060925 k folks, i'm going to change the bindings to java5 although i thought it's probably useless. Now after some work on the Collections-API i found out that it is really useful, especially the typesafety and enums. Still no patches available but things look good, maybe i'll finish something useful already this week.

20060923: The bindings for DrGonzo are ready so far, those for DrHouse (or whatever release Collections will use) will need quite some changes. Those will be splitted into two big parts:

Go with the refactored clientlib API which is already done Implement java collections in some good way which is not done

Neither of the needed patches are available right now, the first one is done though, I just need to clean it a bit. Also one can already use collections in the plain java api with those changes. The second patch(-set) to get nice java collections will need some days/weeks though. One more thought which fits into this news is to probably migrate the bindings to java5, although i don't know if it's of much use. If someone is absolutely against that (even though i don't think that someone reads that page) he should email me.