jvlc #23: make native resources release explicit

[vlc] / bindings / java / core / src / main / java / org / videolan / jvlc / MediaList.java

diff --git a/bindings/java/core/src/main/java/org/videolan/jvlc/MediaList.java b/bindings/java/core/src/main/java/org/videolan/jvlc/MediaList.java
index 5477318340bbf1e65a18029fa06fc8961403de1f..834c4bd9a3496c246a1f010d13e9622dbafeb096 100644 (file)
--- a/bindings/java/core/src/main/java/org/videolan/jvlc/MediaList.java
+++ b/bindings/java/core/src/main/java/org/videolan/jvlc/MediaList.java
@@ -26,11 +26,10 @@
 package org.videolan.jvlc;
 
 import java.util.ArrayList;
-import java.util.LinkedHashSet;
 import java.util.List;
 
 import org.videolan.jvlc.internal.LibVlc.LibVlcEventManager;
-import org.videolan.jvlc.internal.LibVlc.LibVlcMediaDescriptor;
+import org.videolan.jvlc.internal.LibVlc.LibVlcMedia;
 import org.videolan.jvlc.internal.LibVlc.LibVlcMediaList;
 import org.videolan.jvlc.internal.LibVlc.libvlc_exception_t;
 
@@ -42,10 +41,12 @@ public class MediaList
 
     private final LibVlcMediaList instance;
 
-    private final LibVlcEventManager eventManager;
-
     private List<String> items = new ArrayList<String>();
 
+    private LibVlcEventManager eventManager;
+
+    private volatile boolean released;
+    
     public MediaList(JVLC jvlc)
     {
         this.jvlc = jvlc;
@@ -54,12 +55,18 @@ public class MediaList
         eventManager = jvlc.getLibvlc().libvlc_media_list_event_manager(instance, exception);
     }
 
-    public void addMedia(String media)
+    /**
+     * @param mrl The media resource locator to add to the media list.
+     */
+    public void addMedia(String mrl)
     {
-        MediaDescriptor descriptor = new MediaDescriptor(jvlc, media);
+        MediaDescriptor descriptor = new MediaDescriptor(jvlc, mrl);
         addMedia(descriptor);
     }
 
+    /**
+     * @param descriptor The media descriptor to add to the media list.
+     */
     public void addMedia(MediaDescriptor descriptor)
     {
         if (items.contains(descriptor.getMrl()))
@@ -68,30 +75,50 @@ public class MediaList
         }
         items.add(descriptor.getMrl());
         libvlc_exception_t exception = new libvlc_exception_t();
-        jvlc.getLibvlc().libvlc_media_list_add_media_descriptor(instance, descriptor.getInstance(), exception);
+        jvlc.getLibvlc().libvlc_media_list_add_media(instance, descriptor.getInstance(), exception);
     }
 
-    public int itemsCount()
+    /**
+     * @return The current number of items in the media list.
+     */
+    public int size()
     {
         libvlc_exception_t exception = new libvlc_exception_t();
         return jvlc.getLibvlc().libvlc_media_list_count(instance, exception);
     }
 
+    /**
+     * @param descriptor The media descriptor to get the index of.
+     * @return The index of the media descriptor, or -1 if not found.
+     */
     public int indexOf(MediaDescriptor descriptor)
     {
         libvlc_exception_t exception = new libvlc_exception_t();
         return jvlc.getLibvlc().libvlc_media_list_index_of_item(instance, descriptor.getInstance(), exception);
     }
 
+    /**
+     * @param index The index of the media descriptor to get.
+     * @return The media descriptor at the given index.
+     * @throws IndexOutOfBoundsException if index is bigger than size() or < 0, or there are no items in the media_list.
+     */
     public MediaDescriptor getMediaDescriptorAtIndex(int index)
     {
         libvlc_exception_t exception = new libvlc_exception_t();
-        LibVlcMediaDescriptor descriptor = jvlc.getLibvlc().libvlc_media_list_item_at_index(instance, index, exception);
+        if (size() == 0)
+        {
+            throw new IndexOutOfBoundsException();
+        }
+        if (index < 0 || index > size())
+        {
+            throw new IndexOutOfBoundsException();
+        }
+        LibVlcMedia descriptor = jvlc.getLibvlc().libvlc_media_list_item_at_index(instance, index, exception);
         return new MediaDescriptor(jvlc, descriptor);
     }
 
     /**
-     * @param index The index of the media to remove
+     * @param index The index of the media to remove.
      * @return True if the media was successfully removed, false otherwise.
      */
     public boolean removeMedia(int index)
@@ -107,7 +134,7 @@ public class MediaList
     }
 
     /**
-     * @param media The media descriptor mrl
+     * @param mrl The media descriptor mrl.
      */
     public boolean removeMedia(String mrl)
     {
@@ -118,13 +145,42 @@ public class MediaList
         }
         return removeMedia(index);
     }
+    
+    /**
+     * @param mediaDescriptor The media descriptor to remove.
+     */
+    public boolean removeMedia(MediaDescriptor mediaDescriptor)
+    {
+        String mrl = mediaDescriptor.getMrl();
+        int index = items.indexOf(mrl);
+        if (index == -1)
+        {
+            return false;
+        }
+        return removeMedia(index);
+    }
+    
+    /**
+     * Removes all items from the media list.
+     */
+    public void clear()
+    {
+        for (int i = 0; i < size(); i++)
+        {
+            removeMedia(i);
+        }
+    }
 
+    /**
+     * @param descriptor The media descriptor to insert.
+     * @param index The index of the inserted media descriptor.
+     */
     public void insertMediaDescriptor(MediaDescriptor descriptor, int index)
     {
         libvlc_exception_t exception = new libvlc_exception_t();
         jvlc
             .getLibvlc()
-            .libvlc_media_list_insert_media_descriptor(instance, descriptor.getInstance(), index, exception);
+            .libvlc_media_list_insert_media(instance, descriptor.getInstance(), index, exception);
     }
 
     /**
@@ -133,7 +189,7 @@ public class MediaList
     @Override
     protected void finalize() throws Throwable
     {
-        jvlc.getLibvlc().libvlc_media_list_release(instance);
+        release();
         super.finalize();
     }
 
@@ -147,17 +203,19 @@ public class MediaList
     }
 
     /**
-     * @param mediaDescriptor
+     * 
      */
-    public boolean removeMedia(MediaDescriptor mediaDescriptor)
+    public void release()
     {
-        String mrl = mediaDescriptor.getMrl();
-        int index = items.indexOf(mrl);
-        if (index == -1)
+        if (released)
         {
-            return false;
+            return;
         }
-        return removeMedia(index);
+        released = true;
+        
+        jvlc.getLibvlc().libvlc_media_list_release(instance);
     }
 
+
+
 }