Refactor GLib package; remove some old code from GObject API (eg. Closure) and deprecate other things planned for removal by v1; add GLibException to remove dependency on main gstreamer package; add code to help remove GErrorStruct from GError API.

Author: neilcsmith-net

src/org/freedesktop/gstreamer/glib/GCancellable.java

@@ -1,3 +1,22 @@
+/* 
+ * Copyright (c) 2019 Neil C Smith
+ * Copyright (c) 2016 Isaac Raño Jares
+ * 
+ * This file is part of gstreamer-java.
+ *
+ * This code is free software: you can redistribute it and/or modify it under 
+ * the terms of the GNU Lesser General Public License version 3 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT 
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License 
+ * version 3 for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package org.freedesktop.gstreamer.glib;
 
 import org.freedesktop.gstreamer.lowlevel.GioAPI;
@@ -10,7 +29,7 @@ public GCancellable() {
 		this(initializer(GioAPI.g_cancellable_new()));
 	}
 
-	public GCancellable(Initializer init) {
+	private GCancellable(Initializer init) {
 		super(init);
 	}
 

src/org/freedesktop/gstreamer/glib/GDate.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (c) 2019 Neil C Smith
  * Copyright (c) 2016 Christophe Lafolet
  * Copyright (c) 2007 Wayne Meissner
  * 
@@ -25,43 +26,51 @@
 
 import com.sun.jna.Pointer;
 
+/**
+ * Wrapper to the GDate data structure.
+ * 
+ * See upstream documentation at <a href="https://developer.gnome.org/glib/stable/glib-Date-and-Time-Functions.html"
+ * >https://developer.gnome.org/glib/stable/glib-Date-and-Time-Functions.html</a>
+ */
 public class GDate extends NativeObject {
     public static final String GTYPE_NAME = "GDate";
     public static final GType GTYPE = GType.valueOf(GTYPE_NAME); 
 
-    public static GDate createInstance(int day, int month, int year) {
-    	return new GDate(GlibAPI.GLIB_API.g_date_new_dmy(day, month , year), false, true);
-    }
-    public static GDate createInstance(int julian_day) {
-    	return new GDate(GlibAPI.GLIB_API.g_date_new_julian(julian_day), false, true);
-    }
-    
+    @Deprecated
     public GDate(Initializer init) {
         super(init);
     }
+    
+    @Deprecated
     public GDate(Pointer ptr, boolean needRef, boolean ownsHandle) {
         this(initializer(ptr, needRef, ownsHandle));
     }
-    
-    @Override
-    protected void disposeNativeHandle(Pointer ptr) {
-        GlibAPI.GLIB_API.g_date_free(ptr);
-    }
-
-    public int getYear() {
-        return GlibAPI.GLIB_API.g_date_get_year(handle());
+    public int getDay() {
+        return GlibAPI.GLIB_API.g_date_get_day(handle());
     }
 
     public int getMonth() {
         return GlibAPI.GLIB_API.g_date_get_month(handle());
     }
-    
-    public int getDay() {
-        return GlibAPI.GLIB_API.g_date_get_day(handle());
+    public int getYear() {
+        return GlibAPI.GLIB_API.g_date_get_year(handle());
     }
 
     @Override
     public String toString() {
         return "" + getYear() + "-" + getMonth() + "-" + getDay();
     }
+    
+    @Override
+    protected void disposeNativeHandle(Pointer ptr) {
+        GlibAPI.GLIB_API.g_date_free(ptr);
+    }
+    
+    public static GDate createInstance(int day, int month, int year) {
+        return new GDate(GlibAPI.GLIB_API.g_date_new_dmy(day, month , year), false, true);
+    }
+    
+    public static GDate createInstance(int julian_day) {
+        return new GDate(GlibAPI.GLIB_API.g_date_new_julian(julian_day), false, true);
+    }
 }

src/org/freedesktop/gstreamer/glib/GError.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (c) 2019 Neil C Smith
  * Copyright (c) 2007 Wayne Meissner
  * 
  * This file is part of gstreamer-java.
@@ -18,36 +19,37 @@
 
 package org.freedesktop.gstreamer.glib;
 
+import java.util.Objects;
 import org.freedesktop.gstreamer.lowlevel.GstAPI.GErrorStruct;
 
 import static org.freedesktop.gstreamer.lowlevel.GlibAPI.GLIB_API;
 
 /**
- * Base gstreamer error type.
+ * Base GLib error type.
  */
 public class GError {
-    /** 
+    
+    private final int code;
+    private final String message;
+    
+    /**
      * Creates a new instance of GError
-     * <p>
-     * <b> Note: </b> This takes ownership of the passed in GErrorStruct.
-     * @param error 
+     * 
+     * @param code native int error code
+     * @param message error message text
      */
+    public GError(int code, String message) {
+        this.code = code;
+        this.message = Objects.requireNonNull(message);
+    }
+    
     // rewrite to accept code and message - handle struct elsewhere
     @Deprecated
     public GError(GErrorStruct error) {
         code = error.getCode();
         message = error.getMessage();
         GLIB_API.g_error_free(error);
     }
-    
-    /**
-     * Gets a string representation of this error.
-     * 
-     * @return a string representing the error.
-     */
-    public String getMessage() {
-        return message;
-    }
     /**
      * Gets a numeric code representing this error.
      * 
@@ -56,7 +58,12 @@ public String getMessage() {
     public final int getCode() {
         return code;
     }
-    
-    private final int code;
-    private final String message;
+    /**
+     * Gets a string representation of this error.
+     *
+     * @return a string representing the error.
+     */
+    public String getMessage() {
+        return message;
+    }
 }

src/org/freedesktop/gstreamer/glib/GInetAddress.java

@@ -1,3 +1,22 @@
+/* 
+ * Copyright (c) 2019 Neil C Smith
+ * Copyright (c) 2016 Isaac Raño Jares
+ * 
+ * This file is part of gstreamer-java.
+ *
+ * This code is free software: you can redistribute it and/or modify it under 
+ * the terms of the GNU Lesser General Public License version 3 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT 
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License 
+ * version 3 for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package org.freedesktop.gstreamer.glib;
 
 import org.freedesktop.gstreamer.lowlevel.GioAPI;
@@ -6,6 +25,7 @@ public class GInetAddress extends GObject{
 
 	public static final String GTYPE_NAME = "GInetAddress";
 
+        @Deprecated
 	public GInetAddress(Initializer init) {
 		super(init);
 	}

src/org/freedesktop/gstreamer/glib/GInetSocketAddress.java

@@ -1,38 +1,54 @@
+/* 
+ * Copyright (c) 2019 Neil C Smith
+ * Copyright (c) 2016 Isaac Raño Jares
+ * 
+ * This file is part of gstreamer-java.
+ *
+ * This code is free software: you can redistribute it and/or modify it under 
+ * the terms of the GNU Lesser General Public License version 3 only, as
+ * published by the Free Software Foundation.
+ *
+ * This code is distributed in the hope that it will be useful, but WITHOUT 
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 
+ * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License 
+ * version 3 for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public License
+ * version 3 along with this work.  If not, see <http://www.gnu.org/licenses/>.
+ */
+
 package org.freedesktop.gstreamer.glib;
 
-import org.freedesktop.gstreamer.glib.GInetAddress;
-import org.freedesktop.gstreamer.glib.GSocketAddress;
 import org.freedesktop.gstreamer.lowlevel.GioAPI;
 
 import com.sun.jna.Pointer;
-import org.freedesktop.gstreamer.GstException;
 
-public class GInetSocketAddress extends GSocketAddress{
+public class GInetSocketAddress extends GSocketAddress {
 
 	public static final String GTYPE_NAME = "GInetSocketAddress";
 
-	
-	protected static Initializer createRawAddress(String address, int port) {
-		Pointer nativePointer = GioAPI.g_inet_socket_address_new_from_string(address, port);
-		if (nativePointer == null) {
-			throw new GstException("Can not create "+GInetSocketAddress.class.getSimpleName()+" for "+address+":"+port+", please check that the IP address is valid, with format x.x.x.x");
-		}
-		return initializer(nativePointer);
-	}
-	
 	public GInetSocketAddress(String address, int port)  {
 		this(createRawAddress(address, port));
 	}
 
+        @Deprecated
 	public GInetSocketAddress(Initializer init) {
 		super(init);
 	}
+        
+        public GInetAddress getAddress() {
+            return (GInetAddress) get("address");
+        }
 
 	public int getPort() {
 		return (Integer) get("port");
 	}
-	
-	public GInetAddress getAddress() {
-		return (GInetAddress) get("address");
-	}
+        
+        private static Initializer createRawAddress(String address, int port) {
+            Pointer nativePointer = GioAPI.g_inet_socket_address_new_from_string(address, port);
+            if (nativePointer == null) {
+                throw new GLibException("Can not create "+GInetSocketAddress.class.getSimpleName()+" for "+address+":"+port+", please check that the IP address is valid, with format x.x.x.x");
+            }
+            return initializer(nativePointer);
+        }
 }

src/org/freedesktop/gstreamer/glib/GLib.java

@@ -1,4 +1,8 @@
 /* 
+ * 
+ * Copyright (c) 2019 Neil C Smith
+ * Copyright (c) 2018 Ingo Randalf
+ *
  * This file is part of gstreamer-java.
  *
  * gstreamer-java is free software: you can redistribute it and/or modify
@@ -18,17 +22,71 @@
 
 import org.freedesktop.gstreamer.lowlevel.GlibAPI;
 
+/**
+ * Miscellaneous Utility Functions — a selection of portable utility functions from GLib
+ * 
+ * Documentation derived from https://developer.gnome.org/glib/stable/glib-Miscellaneous-Utility-Functions.html#g-setenv
+ */
 public class GLib {
-    
-    public static boolean setEnv(String variable, final String value, boolean overwrite) {        
-        return GlibAPI.GLIB_API.g_setenv(variable, value, overwrite);       
+
+    /**
+     * Sets an environment variable. On UNIX, both the variable's name and value
+     * can be arbitrary byte strings, except that the variable's name cannot
+     * contain '='. On Windows, they should be in UTF-8.
+     *
+     * Note that on some systems, when variables are overwritten, the memory
+     * used for the previous variables and its value isn't reclaimed.
+     *
+     * You should be mindful of the fact that environment variable handling in
+     * UNIX is not thread-safe, and your program may crash if one thread calls
+     * g_setenv() while another thread is calling getenv(). (And note that many
+     * functions, such as gettext(), call getenv() internally.) This function is
+     * only safe to use at the very start of your program, before creating any
+     * other threads (or creating objects that create worker threads of their
+     * own).
+     * 
+     * @param variable the environment variable to set, must not contain '='. 
+     * @param value the value to set the variable to.
+     * @param overwrite whether to change the variable if it already exists.
+     * @return FALSE if the environment variable couldn't be set.
+     */
+    public static boolean setEnv(String variable, final String value, boolean overwrite) {
+        return GlibAPI.GLIB_API.g_setenv(variable, value, overwrite);
     }
-    
-    public static String getEnv(String variable) {       
-        return GlibAPI.GLIB_API.g_getenv(variable);       
-    }   
-    
+
+    /**
+     * Returns the value of an environment variable.
+     *
+     * On UNIX, the name and value are byte strings which might or might not be
+     * in some consistent character set and encoding. On Windows, they are in
+     * UTF-8. On Windows, in case the environment variable's value contains
+     * references to other environment variables, they are expanded.
+     * 
+     * @param variable the environment variable to get. 
+     * @return the value of the environment variable, or NULL if the environment
+     * variable is not found.
+     */
+    public static String getEnv(String variable) {
+        return GlibAPI.GLIB_API.g_getenv(variable);
+    }
+
+    /**
+     * Removes an environment variable from the environment.
+     *
+     * Note that on some systems, when variables are overwritten, the memory
+     * used for the previous variables and its value isn't reclaimed.
+     *
+     * You should be mindful of the fact that environment variable handling in
+     * UNIX is not thread-safe, and your program may crash if one thread calls
+     * g_unsetenv() while another thread is calling getenv(). (And note that
+     * many functions, such as gettext(), call getenv() internally.) This
+     * function is only safe to use at the very start of your program, before
+     * creating any other threads (or creating objects that create worker
+     * threads of their own).
+     *
+     * @param variable the environment variable to remove, must not contain '='.
+     */
     public static void unsetEnv(String variable) {
-        GlibAPI.GLIB_API.g_unsetenv(variable);       
+        GlibAPI.GLIB_API.g_unsetenv(variable);
     }
 }