grizzlyxp homepage

[Back to main page] [Back to project page] [Back to Java AniDB API]

Java AniDB API - Beginner's guide

This is only a short introduction to the Java AniDB API. For more information please look at the Javadoc in the documentation section of the project page.

Before you are using this library I recommend to read (or glance through) the following page: UDP API Definition. I think this way you will gain a deeper insight how the communication works, what you should do and what you shouldn't do.

First I will point out that there are two ways of using the library: Beginner can make use of the main methods and do the library all of the work in the background (like flood protection and caching). Experts can configure everything to their needs or do it with their own code by disabling this functions. At least this are the two design goals.

But let's get started with some code:

UdpConnectionFactory and UdpConnection

The UdpConnectionFactory is the starting point of the library. This class will connect you to AniDB and return a UdpConnection object which is the main object you have to deal all the time:

            UdpConnectionFactory factory;
            UdpConnection conn = null;
            
            factory = UdpConnectionFactory.getInstance();
            try {
                conn = factory.connect(1025);
                
                // Here you can insert your queries.
                
            } catch (Throwable t) {
		t.printStackTrace();
	    } finally {
		try {
                    if (conn != null) {
			conn.close();
                    }
		} catch (Throwable t) {
                    t.printStackTrace();
		}
	    }

First you will fetch an instance of the class UdpConnectionFactory. After that you connect to AniDB with the local port 1025 and get a UdpConnection object. If we speak about the AniDB UDP API we also speaking about UDP. This is in comparision to TCP a stateless protocol. So you should allways call the close() method. Otherwise AniDB will keep the connection open for some time which will cause unnecessary load for the server.

There are some commands you can use now and some you have to authenticate your client and yourself for. Some of the commands which works also in the un-authenticate state are ping() and getServerVersion(). But for most of the commands you have to authenticate:

                conn.authenticate("<anidb username>", "<anidb password>");

or if you want to authenticate your own client instead of the library:

                conn.authenticate("<anidb username>", "<anidb password>", "<clientname>", <clientversion>);

For more information see also: authenticate(String, String) and authenticate(String, String, String, int)

Now you can use all the other commands. One point at the end of the guide: The return values from the data command methods.

All the returned objects are POJOs. Some of them contain other objects, like objects of the Episode class which contains a Anime object. So if you want to get the anime Id, you have to get the anime object from the episode object and get the anime Id from it. Maybe it looks a little bit long-drawn-out, but is a design decission for extensions in the future (e.g. 1st and 2nd level caching).
The hashCode() and equals(Object) methods are implemented for all classes of net.anidb.* and net.anidb.udp.mask.*. But for some classes they are only working under special circumstances - as it is not reasonable in every state. An example: For the class Anime hashCode() and equals(Object) will only produce result which make sense if the anime Id is set.

[Back to main page] [Back to project page] [Back to Java AniDB API]