Version API (#137)

* Require version to be passed into init(), check version is satisfied, and provide methods to test or require version based on that passed into init().

* Add @Gst.Since annotation for use on classes, methods or fields that require a GStreamer version higher than baseline (1.8). Shows up in Javadoc and runtime introspectable.

* Add testing for new Gst.init() with version request failures.

Author: neilcsmith-net

src/org/freedesktop/gstreamer/Gst.java

@@ -1,6 +1,6 @@
 /* 
+ * Copyright (c) 2019 Neil C Smith
  * Copyright (c) 2018 Antonio Morales
- * Copyright (c) 2018 Neil C Smith
  * Copyright (c) 2007 Wayne Meissner
  * 
  * This file is part of gstreamer-java.
@@ -60,6 +60,9 @@
 import com.sun.jna.Pointer;
 import com.sun.jna.ptr.IntByReference;
 import com.sun.jna.ptr.PointerByReference;
+import java.lang.annotation.Documented;
+import java.lang.annotation.Retention;
+import java.lang.annotation.RetentionPolicy;
 import java.util.Arrays;
 import java.util.logging.Level;
 import static org.freedesktop.gstreamer.lowlevel.GstParseAPI.GSTPARSE_API;
@@ -70,14 +73,19 @@
  */
 @SuppressWarnings("deprecation")
 public final class Gst {
-	private static Logger logger = Logger.getLogger(Gst.class.getName());
+    
+    private final static Logger LOG = Logger.getLogger(Gst.class.getName());
+    private final static AtomicInteger INIT_COUNT = new AtomicInteger(0);
+    private final static boolean CHECK_VERSIONS = !Boolean.getBoolean("gstreamer.suppressVersionChecks");
+    
 
     private static ScheduledExecutorService executorService;
     private static volatile CountDownLatch quit = new CountDownLatch(1);
     private static GMainContext mainContext;
     private static boolean useDefaultContext = false;
-    private static final AtomicInteger initCount = new AtomicInteger(0);
-    private static List<Runnable> shutdownTasks = Collections.synchronizedList(new ArrayList<Runnable>());  
+    private static List<Runnable> shutdownTasks = Collections.synchronizedList(new ArrayList<Runnable>());
+    // set minorVersion to a value guaranteed to be >= anything else unless set in init()
+    private static int minorVersion = Integer.MAX_VALUE;
 
     public static class NativeArgs {
         public IntByReference argcRef;
@@ -135,7 +143,7 @@ private Gst() {
     public static Version getVersion() {
         long[] major = { 0 }, minor = { 0 }, micro = { 0 }, nano = { 0 };
         GST_API.gst_version(major, minor, micro, nano);
-        return new Version(major[0], minor[0], micro[0], nano[0]);
+        return new Version((int) major[0], (int) minor[0], (int) micro[0], (int) nano[0]);
     }
 
     /**
@@ -167,7 +175,7 @@ public static void setSegTrap(boolean enabled) {
      * @return true if the GStreamer library already initialized.
      */
     public static synchronized final boolean isInitialized() {
-    	return initCount.get() > 0;
+    	return INIT_COUNT.get() > 0;
     }
 
     /**
@@ -234,7 +242,7 @@ public static Element parseLaunch(String pipelineDescription, List<GError> error
             if (errors != null) {
                 errors.add(new GError(new GErrorStruct(err[0])));
             } else {
-                logger.log(Level.WARNING, new GError(new GErrorStruct(err[0])).getMessage());
+                LOG.log(Level.WARNING, new GError(new GErrorStruct(err[0])).getMessage());
             }
         }
 
@@ -283,7 +291,7 @@ public static Element parseLaunch(String[] pipelineDescription, List<GError> err
             if (errors != null) {
                 errors.add(new GError(new GErrorStruct(err[0])));
             } else {
-                logger.log(Level.WARNING, new GError(new GErrorStruct(err[0])).getMessage());
+                LOG.log(Level.WARNING, new GError(new GErrorStruct(err[0])).getMessage());
             }
         }
 
@@ -330,7 +338,7 @@ public static Bin parseBinFromDescription(String binDescription, boolean ghostUn
             if (errors != null) {
                 errors.add(new GError(new GErrorStruct(err[0])));
             } else {
-                logger.log(Level.WARNING, new GError(new GErrorStruct(err[0])).getMessage());
+                LOG.log(Level.WARNING, new GError(new GErrorStruct(err[0])).getMessage());
             }
         }
 
@@ -411,8 +419,46 @@ public static GMainContext getMainContext() {
      *
      * @throws org.freedesktop.gstreamer.GstException
      */
+    @Deprecated
     public static final void init() throws GstException {
-        init("unknown", new String[] {});
+        init(new Version(1, 8), "gst1-java-core");
+    }
+    
+    /**
+     * Initializes the GStreamer library.
+     * <p> This is a shortcut if no arguments are to be passed to gstreamer.
+     *
+     * @param requiredVersion 
+     * @throws org.freedesktop.gstreamer.GstException
+     */
+    public static final void init(Version requiredVersion) throws GstException {
+        init(requiredVersion, "gst1-java-core");
+    }
+    
+    
+    /**
+     * Initializes the GStreamer library.
+     * <p> This sets up internal path lists, registers built-in elements, and 
+     * loads standard plugins.
+     *
+     * <p>
+     * This method should be called before calling any other GLib functions. If
+     * this is not an option, your program must initialise the GLib thread system
+     * using g_thread_init() before any other GLib functions are called.
+     *
+     * <p>
+     * <b>Note:</b><p>
+     * This method will throw a GstException if it fails.
+     * 
+     * @param progname the java program name.
+     * @param args the java argument list.
+     * @return the list of arguments with any gstreamer specific options stripped 
+     * out.
+     * @throws org.freedesktop.gstreamer.GstException
+     */
+    @Deprecated
+    public static synchronized final String[] init(String progname, String ... args) throws GstException {
+        return init(new Version(1, 8), progname, args);
     }
 
     /**
@@ -429,29 +475,58 @@ public static final void init() throws GstException {
      * <b>Note:</b><p>
      * This method will throw a GstException if it fails.
      * 
+     * @param requestedVersion the minimum requested GStreamer version.
      * @param progname the java program name.
      * @param args the java argument list.
      * @return the list of arguments with any gstreamer specific options stripped 
      * out.
      * @throws org.freedesktop.gstreamer.GstException
      */
-    public static synchronized final String[] init(String progname, String[] args) throws GstException {
+    public static synchronized final String[] init(Version requestedVersion,
+            String progname, String ... args) throws GstException {
+                  
+        if (CHECK_VERSIONS) {
+            Version availableVersion = getVersion();
+            if (requestedVersion.getMajor() != 1 || availableVersion.getMajor() != 1) {
+                throw new GstException("gst1-java-core only supports GStreamer 1.x");
+            }
+            if (requestedVersion.getMinor() < 8) {
+                requestedVersion = new Version(1, 8);
+            }
+            if (!availableVersion.checkSatisfies(requestedVersion)) {
+                throw new GstException(String.format(
+                        "The requested version of GStreamer is not available\nRequested : %s\nAvailable : %s\n",
+                        requestedVersion, availableVersion));
+            }
+        }
+        
         //
         // Only do real init the first time through
         //
-        if (initCount.getAndIncrement() > 0) {
+        if (INIT_COUNT.getAndIncrement() > 0) {
+            if (CHECK_VERSIONS) {
+                if (requestedVersion.getMinor() > minorVersion) {
+                    minorVersion = (int) requestedVersion.getMinor();
+                }
+            }
             return args;
         }
+        
         NativeArgs argv = new NativeArgs(progname, args);
 
         Pointer[] error = { null };
         if (!GST_API.gst_init_check(argv.argcRef, argv.argvRef, error)) {
-            initCount.decrementAndGet();
+            INIT_COUNT.decrementAndGet();
             throw new GstException(new GError(new GErrorStruct(error[0])));
         }
 
-        logger.fine("after gst_init, argc=" + argv.argcRef.getValue());
-
+        LOG.fine("after gst_init, argc=" + argv.argcRef.getValue());
+        
+        Version runningVersion = getVersion();
+        if (runningVersion.getMajor() != 1) {
+            LOG.warning("gst1-java-core only supports GStreamer 1.x");
+        }
+        
         if (useDefaultContext) {
             mainContext = GMainContext.getDefaultContext();
             executorService = new MainContextExecutorService(mainContext);
@@ -461,6 +536,11 @@ public static synchronized final String[] init(String progname, String[] args) t
         }
         quit = new CountDownLatch(1);
         loadAllClasses();
+        
+        if (CHECK_VERSIONS) {
+            minorVersion = requestedVersion.getMinor();
+        }
+        
         return argv.toStringArray();
     }
 
@@ -473,7 +553,7 @@ public static synchronized final void deinit() {
         //
         // Only perform real shutdown if called as many times as Gst.init() is
         //
-        if (initCount.decrementAndGet() > 0) {
+        if (INIT_COUNT.decrementAndGet() > 0) {
             return;
         }
         // Perform any cleanup tasks
@@ -527,6 +607,36 @@ public static void setUseDefaultContext(boolean useDefault) {
         useDefaultContext = useDefault;
     }
 
+    /**
+     * Checks that the version of GStreamer requested in init() satisfies the
+     * given version or throws an exception.
+     * 
+     * @param major major version, only 1 is supported
+     * @param minor minor version required
+     * @throws GstException if the requested version support was not requested
+     */
+    public static void checkVersion(int major, int minor) {
+        if (CHECK_VERSIONS && (major != 1 || minor > minorVersion)) {
+            throw new GstException("Not supported by requested GStreamer version");
+        }
+    }
+    
+    /**
+     * Tests that the version of GStreamer requested in init() satisfies the
+     * given version.
+     * 
+     * @param major major version, only 1 is supported
+     * @param minor minor version required
+     * @return boolean whether the version requirement can be satisfied
+     */
+    public static boolean testVersion(int major, int minor) {
+        if (CHECK_VERSIONS && (major != 1 || minor > minorVersion)) {
+            return false;
+        }
+        return true;
+    }
+
+    
     // Make the gstreamer executor threads daemon, so they don't stop the main 
     // program from exiting
     private static final ThreadFactory threadFactory = new ThreadFactory() {
@@ -640,4 +750,18 @@ private static synchronized void loadAllClasses() {
                     URIDecodeBin.class,
                     WebRTCBin.class
             );
+    
+    /**
+     * Annotation on classes, methods or fields to show the required GStreamer
+     * version. This should particularly be used where the version required is higher
+     * than the current baseline supported version (GStreamer 1.8)
+     */
+    @Retention(RetentionPolicy.RUNTIME)
+    @Documented
+    public static @interface Since {
+        public int major() default 1;
+        public int minor();
+    }
+    
+    
 }

src/org/freedesktop/gstreamer/Version.java

@@ -1,5 +1,6 @@
 /* 
- * Copyright (c) 2007, 2008 Wayne Meissner
+ * Copyright (c) 2019 Neil C Smith
+ * Copyright (c) 2008 Wayne Meissner
  * 
  * This file is part of gstreamer-java.
  *
@@ -19,10 +20,17 @@
 package org.freedesktop.gstreamer;
 
 /**
- * Describes the version of gstreamer currently in use.
+ * Describes a GStreamer version.
  */
 public class Version {
-    public Version(long major, long minor, long micro, long nano) {
+    
+    private final int major, minor, micro, nano;
+    
+    public Version(int major, int minor) {
+        this(major, minor, 0, 0);
+    }
+    
+    public Version(int major, int minor, int micro, int nano) {
         this.major = major;
         this.minor = minor;
         this.micro = micro;
@@ -42,35 +50,46 @@ public String toString() {
     }
 
     /**
-     * Gets the major version of GStreamer at compile time.
+     * Gets the major version of GStreamer.
      * @return the major version.
      */
-    public long getMajor() {
+    public int getMajor() {
         return major;
     }
 
     /**
-     * Gets the minor version of GStreamer at compile time.
+     * Gets the minor version of GStreamer.
      * @return the minor version.
      */
-    public long getMinor() {
+    public int getMinor() {
         return minor;
     }
 
     /**
-     * Gets the micro version of GStreamer at compile time.
+     * Gets the micro version of GStreamer.
      * @return the micro version.
      */
-    public long getMicro() {
+    public int getMicro() {
         return micro;
     }
 
     /**
-     * Gets the nano version of GStreamer at compile time.
+     * Gets the nano version of GStreamer.
      * @return the nano version.
      */
-    public long getNano() {
+    public int getNano() {
         return nano;
     }
-    private final long major, minor, micro, nano;
+    
+    /**
+     * Check whether this version is equal to or greater than the passed in 
+     * version. Roughly comparable to GST_CHECK_VERSION
+     * @param required version to check against
+     * @return true if this version satisfies the required version
+     */
+    public boolean checkSatisfies(Version required) {
+        return (major == required.major && minor > required.minor) ||
+                (major == required.major && minor == required.minor && micro >= required.micro);
+    }
+    
 }

test/org/freedesktop/gstreamer/InitTest.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (c) 2019 Neil C Smith
  * Copyright (c) 2007 Wayne Meissner
  * 
  * This file is part of gstreamer-java.
@@ -37,8 +38,22 @@ public InitTest() {
     }
     @Test
     public void testInit() {
-        String[] args = Gst.init("InitTest", new String[] { "--gst-plugin-spew" });
+        Version available = Gst.getVersion();
+        Version notAvailable = new Version(available.getMajor(), available.getMinor() + 2);
+        try {
+            Gst.init(notAvailable);
+            assertTrue("Version check exception not thrown!", false);
+        } catch (GstException ex) {
+            System.out.println("Expected init failure");
+            System.out.println(ex);
+        }
+        String[] args = Gst.init(available, "InitTest", "--gst-plugin-spew");
         assertTrue(args.length == 0);
+        
+        assertTrue(Gst.testVersion(available.getMajor(), available.getMinor()));
+        assertTrue(Gst.testVersion(available.getMajor(), available.getMinor() - 2));
+        assertTrue(!Gst.testVersion(notAvailable.getMajor(), notAvailable.getMinor()));
+        
         Gst.deinit();
     }
     @BeforeClass