Update Gst.parseLaunch behaviour, deprecate replaced methods (#113)

* test Gst.parseBinFromDescription and Gst.parseLaunch

* Update parse methods to support single elements.

* Update parseLaunch tests to work with Element return; add single element test to check that a Pipeline class isn't returned.

* Tidy up documentation.

Author: neilcsmith-net

src/org/freedesktop/gstreamer/Bin.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (c) 2018 Neil C Smith
  * Copyright (c) 2016 Christophe Lafolet
  * Copyright (c) 2009 Levente Farkas
  * Copyright (C) 2007 Wayne Meissner
@@ -88,24 +89,26 @@ public Bin(String name) {
         this(initializer(GSTBIN_API.ptr_gst_bin_new(name), false));
     }
 
-	/**
-	 * Creates a bin from a text bin description. 
-	 * 
-	 * This function allows creation of a bin based on the syntax used in the
-	 * gst-launch utillity.
-	 * 
-	 * @param binDecription the command line describing the bin
-	 * @param ghostUnlinkedPads whether to create ghost pads for the bin from any unlinked pads
-	 * @return The new Bin.
-	 */
-	public static Bin launch(String binDecription, boolean ghostUnlinkedPads) {
-		Pointer[] err = { null };
-		Bin bin = GSTPARSE_API.gst_parse_bin_from_description(binDecription, ghostUnlinkedPads, err);
-		if (bin == null) {
-			throw new GstException(new GError(new GErrorStruct(err[0])));
-		}
-		return bin;
-	}
+    /**
+     * Creates a bin from a text bin description.
+     *
+     * This function allows creation of a bin based on the syntax used in the
+     * gst-launch utillity.
+     *
+     * @param binDecription the command line describing the bin
+     * @param ghostUnlinkedPads whether to create ghost pads for the bin from
+     * any unlinked pads
+     * @return The new Bin.
+     */
+    @Deprecated
+    public static Bin launch(String binDecription, boolean ghostUnlinkedPads) {
+        Pointer[] err = {null};
+        Bin bin = GSTPARSE_API.gst_parse_bin_from_description(binDecription, ghostUnlinkedPads, err);
+        if (bin == null) {
+            throw new GstException(new GError(new GErrorStruct(err[0])));
+        }
+        return bin;
+    }
 
     /**
      * Adds an Element to this Bin.

src/org/freedesktop/gstreamer/Gst.java

@@ -1,5 +1,5 @@
 /* 
- * Copyright (c) 2017 Neil C Smith
+ * Copyright (c) 2018 Neil C Smith
  * Copyright (c) 2007 Wayne Meissner
  * 
  * This file is part of gstreamer-java.
@@ -213,14 +213,16 @@ public static void quit() {
      * to play the pipeline.
      * 
      * @param pipelineDescription  the command line describing the pipeline
+     * @param errors a list that any errors will be added to
      * @return a new element on success. 
-     *         If more than one toplevel element is specified by 
-     *         the pipeline_description , all elements are put into a GstPipeline, 
-     *         which than is returned. 
+     *         If more than one top-level element is specified by 
+     *         the pipeline_description , all elements are put into a Pipeline, 
+     *         which then is returned.
+     * @throws GstException if the pipeline / element could not be created
      */
-    public static Pipeline parseLaunch(String pipelineDescription, List<GError> errors) {
+    public static Element parseLaunch(String pipelineDescription, List<GError> errors) {
         Pointer[] err = { null };
-        Pipeline pipeline = GSTPARSE_API.gst_parse_launch(pipelineDescription, err);
+        Element pipeline = GSTPARSE_API.gst_parse_launch(pipelineDescription, err);
         if (pipeline == null) {
             throw new GstException(new GError(new GErrorStruct(err[0])));
         }
@@ -235,8 +237,24 @@ public static Pipeline parseLaunch(String pipelineDescription, List<GError> erro
         }
 
         return pipeline;
-    }    
-    public static Pipeline parseLaunch(String pipelineDescription) {
+    }
+    
+    /**
+     * Create a new pipeline based on command line syntax.
+     * 
+     * Please note that you might get a return value that is not NULL even 
+     * though the error is set. 
+     * In this case there was a recoverable parsing error and you can try 
+     * to play the pipeline.
+     * 
+     * @param pipelineDescription  the command line describing the pipeline
+     * @return a new element on success. 
+     *         If more than one top-level element is specified by 
+     *         the pipeline_description , all elements are put into a Pipeline, 
+     *         which then is returned.
+     * @throws GstException if the pipeline / element could not be created
+     */
+    public static Element parseLaunch(String pipelineDescription) {
         return parseLaunch(pipelineDescription, null);
     }
 
@@ -247,11 +265,13 @@ public static Pipeline parseLaunch(String pipelineDescription) {
      * An error does not mean that the pipeline could not be constructed.
      * 
      * @param pipelineDescription An array of strings containing the command line describing the pipeline.
+     * @param errors a list that any errors will be added to
      * @return a new element on success. 
+     * @throws GstException if the pipeline / element could not be created
      */
-    public static Pipeline parseLaunch(String[] pipelineDescription, List<GError> errors) {
+    public static Element parseLaunch(String[] pipelineDescription, List<GError> errors) {
         Pointer[] err = { null };
-        Pipeline pipeline = GSTPARSE_API.gst_parse_launchv(pipelineDescription, err);
+        Element pipeline = GSTPARSE_API.gst_parse_launchv(pipelineDescription, err);
         if (pipeline == null) {
             throw new GstException(new GError(new GErrorStruct(err[0])));
         }
@@ -267,7 +287,18 @@ public static Pipeline parseLaunch(String[] pipelineDescription, List<GError> er
 
         return pipeline;
     }
-    public static Pipeline parseLaunch(String[] pipelineDescription) {
+    
+    /**
+     * Create a new element based on command line syntax. 
+     * 
+     * error will contain an error message if an erroneous pipeline is specified. 
+     * An error does not mean that the pipeline could not be constructed.
+     * 
+     * @param pipelineDescription An array of strings containing the command line describing the pipeline.
+     * @return a new element on success. 
+     * @throws GstException if the pipeline / element could not be created
+     */
+    public static Element parseLaunch(String[] pipelineDescription) {
         return parseLaunch(pipelineDescription, null);
     }
 
@@ -279,7 +310,9 @@ public static Pipeline parseLaunch(String[] pipelineDescription) {
     * 
     * @param binDescription the command line describing the bin
     * @param ghostUnlinkedPads whether to create ghost pads for the bin from any unlinked pads
+    * @param errors list that any errors will be added to
     * @return The new Bin.
+    * @throws GstException if the bin could not be created
     */
    public static Bin parseBinFromDescription(String binDescription, boolean ghostUnlinkedPads, List<GError> errors) {
 
@@ -301,6 +334,18 @@ public static Bin parseBinFromDescription(String binDescription, boolean ghostUn
 
         return bin;
    }
+   
+   /**
+    * Creates a bin from a text bin description. 
+    * 
+    * This function allows creation of a bin based on the syntax used in the
+    * gst-launch utillity.
+    * 
+    * @param binDescription the command line describing the bin
+    * @param ghostUnlinkedPads whether to create ghost pads for the bin from any unlinked pads
+    * @return The new Bin.
+    * @throws GstException if the bin could not be created
+    */
    public static Bin parseBinFromDescription(String binDescription, boolean ghostUnlinkedPads) {
        return parseBinFromDescription(binDescription, ghostUnlinkedPads, null);
    }

src/org/freedesktop/gstreamer/Pipeline.java

@@ -1,8 +1,8 @@
 /* 
- * Copyright (c) 2015 Neil C Smith
- * Copyright (c) 2007,2008 Wayne Meissner
- * Copyright (C) 1999,2000 Erik Walthinsen <omega@cse.ogi.edu>
- *                    2004,2005 Wim Taymans <wim@fluendo.com>
+ * Copyright (c) 2018 Neil C Smith
+ * Copyright (c) 2008 Wayne Meissner
+ * Copyright (C) 2000 Erik Walthinsen <omega@cse.ogi.edu>
+ *               2005 Wim Taymans <wim@fluendo.com>
  * 
  * This file is part of gstreamer-java.
  *
@@ -131,9 +131,10 @@ private static Initializer initializer(String name) {
      * @param pipelineDecription  the command line describing the pipeline
      * @return The new Pipeline.
      */
+    @Deprecated
     public static Pipeline launch(String pipelineDecription) {
         Pointer[] err = { null };
-        Pipeline pipeline = GSTPARSE_API.gst_parse_launch(pipelineDecription, err);
+        Pipeline pipeline = (Pipeline) GSTPARSE_API.gst_parse_launch(pipelineDecription, err);
         if (pipeline == null) {
             throw new GstException(new GError(new GErrorStruct(err[0])));
         }
@@ -156,9 +157,10 @@ public static Pipeline launch(String pipelineDecription) {
      * @param pipelineDecription An array of strings containing the command line describing the pipeline.
      * @return The new Pipeline.
      */
+    @Deprecated
     public static Pipeline launch(String... pipelineDecription) {
         Pointer[] err = { null };
-        Pipeline pipeline = GSTPARSE_API.gst_parse_launchv(pipelineDecription, err);
+        Pipeline pipeline = (Pipeline) GSTPARSE_API.gst_parse_launchv(pipelineDecription, err);
         if (pipeline == null) {
             throw new GstException(new GError(new GErrorStruct(err[0])));
         }

src/org/freedesktop/gstreamer/lowlevel/GstParseAPI.java

@@ -24,16 +24,17 @@
 import org.freedesktop.gstreamer.lowlevel.annotations.CallerOwnsReturn;
 
 import com.sun.jna.Pointer;
+import org.freedesktop.gstreamer.Element;
 
 /**
  * gstparse functions
  */
 public interface GstParseAPI extends com.sun.jna.Library {
 	GstParseAPI GSTPARSE_API = GstNative.load(GstParseAPI.class);
 
-    @CallerOwnsReturn Pipeline gst_parse_launch(String pipeline_description, Pointer[] error);
-    @CallerOwnsReturn Pipeline gst_parse_launchv(String[] pipeline_description, Pointer[] error);
-    @CallerOwnsReturn Pipeline gst_parse_launch(String pipeline_description, GstAPI.GErrorStruct[] error);
-    @CallerOwnsReturn Pipeline gst_parse_launchv(String[] pipeline_description, GstAPI.GErrorStruct[] error);
+    @CallerOwnsReturn Element gst_parse_launch(String pipeline_description, Pointer[] error);
+    @CallerOwnsReturn Element gst_parse_launchv(String[] pipeline_description, Pointer[] error);
+    @CallerOwnsReturn Element gst_parse_launch(String pipeline_description, GstAPI.GErrorStruct[] error);
+    @CallerOwnsReturn Element gst_parse_launchv(String[] pipeline_description, GstAPI.GErrorStruct[] error);
     @CallerOwnsReturn Bin gst_parse_bin_from_description(String bin_description, boolean ghost_unlinked_pads,Pointer[] error);
 }

test/org/freedesktop/gstreamer/BinTest.java

@@ -19,6 +19,7 @@
 
 package org.freedesktop.gstreamer;
 
+import java.util.ArrayList;
 import static org.junit.Assert.assertEquals;
 import static org.junit.Assert.assertFalse;
 import static org.junit.Assert.assertNotNull;
@@ -242,58 +243,80 @@ public void iterateSorted() {
     }
 
     @Test
-    public void testLaunch() {
-        Bin bin = Bin.launch("fakesrc ! fakesink", false);
+    public void testParseBin() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+        Bin bin = Gst.parseBinFromDescription("fakesrc ! fakesink", false, errors);
         assertNotNull("Bin not created", bin);
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }   
     @Test
-    public void testLaunchElementCount() {
-        Bin bin = Bin.launch("fakesrc ! fakesink", false);
+    public void testParseBinElementCount() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+        Bin bin = Gst.parseBinFromDescription("fakesrc ! fakesink", false, errors);
         assertEquals("Number of elements in pipeline incorrect", 2, bin.getElements().size());
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }
     @Test
-    public void testLaunchSrcElement() {
-    	Bin bin = Bin.launch("fakesrc ! fakesink", false);
+    public void testParseBinSrcElement() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+    	Bin bin = Gst.parseBinFromDescription("fakesrc ! fakesink", false, errors);
         assertEquals("First element not a fakesrc", "fakesrc", bin.getSources().get(0).getFactory().getName());
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }
     @Test
-    public void testLaunchSinkElement() {
-    	Bin bin = Bin.launch("fakesrc ! fakesink", false);
+    public void testParseBinSinkElement() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+    	Bin bin = Gst.parseBinFromDescription("fakesrc ! fakesink", false, errors);
         assertEquals("First element not a fakesink", "fakesink", bin.getSinks().get(0).getFactory().getName());
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }
     @Test
-    public void testLaunchDisabledGhostPadsForSource() {
-    	Bin bin = Bin.launch("fakesrc", false);
+    public void testParseBinDisabledGhostPadsForSource() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+    	Bin bin = Gst.parseBinFromDescription("fakesrc", false, errors);
     	assertEquals("Number of src pads incorrect", 0, bin.getSrcPads().size());
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }
     @Test
-    public void testLaunchDisabledGhostPadsForSink() {
-    	Bin bin = Bin.launch("fakesink", false);
+    public void testParseBinDisabledGhostPadsForSink() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+    	Bin bin = Gst.parseBinFromDescription("fakesink", false, errors);
     	assertEquals("Number of sink pads incorrect", 0, bin.getSinkPads().size());
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }
     @Test
-    public void testLaunchEnabledGhostPadsForSource() {
-    	Bin bin = Bin.launch("fakesrc", true);
+    public void testParseBinEnabledGhostPadsForSource() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+    	Bin bin = Gst.parseBinFromDescription("fakesrc", true, errors);
     	assertEquals("Number of src pads incorrect", 1, bin.getSrcPads().size());
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }
     @Test
-    public void testLaunchEnabledGhostPadsForSink() {
-    	Bin bin = Bin.launch("fakesink", true);
+    public void testParseBinEnabledGhostPadsForSink() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+    	Bin bin = Gst.parseBinFromDescription("fakesink", true, errors);
     	assertEquals("Number of sink pads incorrect", 1, bin.getSinkPads().size());
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }
     @Test
-    public void testLaunchEnabledGhostPadsForSourceWithNoUsablePads() {
-    	Bin bin = Bin.launch("fakesrc ! fakesink", true);
+    public void testParseBinEnabledGhostPadsForSourceWithNoUsablePads() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+    	Bin bin = Gst.parseBinFromDescription("fakesrc ! fakesink", true, errors);
     	assertEquals("Number of src pads incorrect", 0, bin.getSrcPads().size());
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }
     @Test
-    public void testLaunchEnabledGhostPadsForSinkWithNoUsablePads() {
-    	Bin bin = Bin.launch("fakesrc ! fakesink", true);
+    public void testParseBinEnabledGhostPadsForSinkWithNoUsablePads() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+    	Bin bin = Gst.parseBinFromDescription("fakesrc ! fakesink", true, errors);
     	assertEquals("Number of sink pads incorrect", 0, bin.getSinkPads().size());
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }
     @Test
-    public void testLaunchEnabledGhostPadsWithNoUsablePads() {
-    	Bin bin = Bin.launch("fakesrc ! fakesink", true);
+    public void testParseBinEnabledGhostPadsWithNoUsablePads() {
+        ArrayList<GError> errors = new ArrayList<GError>();
+    	Bin bin = Gst.parseBinFromDescription("fakesrc ! fakesink", true, errors);
     	assertEquals("Number of pads incorrect", 0, bin.getPads().size());
+        assertEquals("parseBinFromDescription with error!", errors.size(), 0);
     }
 }