PluginDevGuide Listeners

From VuzeWiki
Jump to: navigation, search

This is a work in progress guide on how to implement a download listener.

Brief Overview[edit]

What is a download listener?[edit]

A download listener is an interface that allows you to do something (hopefully useful) when an event occurs in a download. If you are using the Eclipse IDE and have properly configured it like in this guide here, you can use the Project Explorer to go through the interface declaration of a DownloadListener that can be found in the org.gudy.azureus2.plugins.download package.

What do we have to do?[edit]

Because a download listener is an interface in Java, we will have to write a class that implements the methods of said interface, namely DownloadListener. You can read more about interfaces here. After we declare a class, we will have to create an instance of that class and use the appropriate classes and methods to attach that listener to an instantiated object that will fire an event for our DownloadListener to act upon.

Can we do it another, easier, way?[edit]

To be honest, I do not know. I spent a good while in the plugin API (being new to Java and Azureus Plugin Development) trying to figure out how to do this and the fact that this article had not been written until now, did not ease my struggles. It seems a little tricky at first, but I assure you that it can be done.

The code[edit]

What do I need to know?[edit]

Well, if you take a look at the methods of Download, you will quickly find that there is no addListener(DownloadListener) method for it! Don't worry, the DownloadEventNotifier.addListener(DownloadListener) will do the trick. What was that? Download has no getDownloadEventNotifier() to reference the DownloadEventNotifier to call addListener()? That's okay too, because DownloadManager happens to have a method called getGlobalDownloadEventNotifier that will give us just that. And if you have read any of the pages of this Plugin Development Guide then you would know that the PluginInterface that you get when you initialize() a usable plugin has the method getDownloadManager. Now hunting down all the import.* whatevers for this job isn't all that hard. So here is the list ready to copy and paste:
import org.gudy.azureus2.plugins.PluginInterface;
import org.gudy.azureus2.plugins.download.DownloadListener;

Yep, it's really that easy so far.

The DownloadListener class[edit]

Now this part is easy too. Let's define our class. Keep in mind that for this part of the example code, I will use some arbitrary method doSomethingUseful(Download download) which expects a single parameter of Download type. This is the basic outline:
class MyDownloadEventListener implements DownloadListener {
   public void stateChanged(Download download, Int oldState, Int newState){
      doSomethingUseful(download); //Any code could go here. This is just for example!
      return;
      }
   public void positionChanged(Download download, Int oldPosition, Int newPosition){
      return; //Could have been anything that you want to do when a download changes position.
      }
}

Now that we have our download listener class declared properly, we need to go on and attach an instance to the mechanism that will fire an event to it.

Instantiate and attach[edit]

Okay, depending on how you are creating your plugin, we need to create an instance of our listener.

MyDownloadEventListener myListener=new MyDownloadEventListener();

That took care of that. Now that we have an instance of our listener named myListener, we just need to attach it. Again, We are going to start with our handy dandy reference to PluginInterface that we get when we initialize a plugin. For the sake of coherence, I will use plugin_interface as it is used in other parts of this guide.

So, now for the code:
plugin_interface.getDownloadManager().getGlobalDownloadEventNotifier().addListener(myListener);

That will attach our listener and our function doSomethingUseful(download) will execute anytime the state of a download changes. What that function does is up to you. Remember that because we passed this function the reference that our listener gets when it is fired, we have the ability to do things with that particular download such as check the state with newState against the constants Download.ST_QUEUED,Download.ST_PREPARING,Download.ST_SEEDING or Download.ST_DOWNLOADING just to name a few. Look up the package either in your IDE or through The Plugin API to find out all the ST constants for the Download type.

Other things to note[edit]

Your plugin as the listener...[edit]

Your plugin class, the one that implements Plugin and possibly UnloadablePlugin and the like, can also Implement the DownLoadEventListener as long as you define the two functions stateChanged(Download, Int, Int) and positionChanged(Download, Int, Int). Then instead of adding myListener you would add this.

The quality of this page[edit]

I just started programming in Java again and I may have forgotten a thing or two. Also, I am new to the Plugin API so if you have any better ways of doing this, please add your ideas and corrections. This is the VuzeWiki and we ought to share the knowledge with one another. This page was written to 1)Share the knowledge that took me several days to acquire that I could not find altogether someplace else 2)Contribute to the community.

Read On[edit]

The Plugin Development Guide