Update and document org.freedesktop.gstreamer.message package.

Author: neilcsmith-net

src/org/freedesktop/gstreamer/Bus.java

@@ -35,6 +35,7 @@
 import com.sun.jna.Native;
 import com.sun.jna.Pointer;
 import com.sun.jna.ptr.PointerByReference;
+import java.util.Locale;
 
 import org.freedesktop.gstreamer.lowlevel.GstAPI.GErrorStruct;
 import org.freedesktop.gstreamer.lowlevel.GstBusAPI;
@@ -755,7 +756,7 @@ public void run() {
      * @param callback The callback to call when the signal is emitted.
      */
     private <T> void connect(Class<T> listenerClass, T listener, BusCallback callback) {
-        final String signal = listenerClass.getSimpleName().toLowerCase().replaceAll("_", "-");
+        final String signal = listenerClass.getSimpleName().toLowerCase(Locale.ROOT).replace('_', '-');
         connect(signal, listenerClass, listener, callback);
     }
 
@@ -777,15 +778,17 @@ public synchronized <T> void connect(String signal, Class<T> listenerClass, T li
             super.connect(signal, listenerClass, listener, callback);
             return;
         }
-        MessageType type = MessageType.forName(signal);
-        if (type == MessageType.UNKNOWN && "message".equals(signal)) {
+        MessageType type;
+        if ("message".equals(signal)) {
             type = MessageType.ANY;
-        }
-        if (type == MessageType.UNKNOWN) {
-            throw new IllegalArgumentException("Illegal signal: " + signal);
+        } else {
+            //@TODO refactor to stop unnecessary String operations
+            type = MessageType.valueOf(signal.toUpperCase(Locale.ROOT).replace('-', '_'));
         }
         final Map<Class<?>, Map<Object, MessageProxy>> signals = getListenerMap();
-        Map<Object, MessageProxy> m = signals.get(type);
+        // @TODO this was using type so doubtful ever worked
+        // these maps needs relooking at!
+        Map<Object, MessageProxy> m = signals.get(listenerClass);
         if (m == null) {
             m = new HashMap<Object, MessageProxy>();
             signals.put(listenerClass, m);

src/org/freedesktop/gstreamer/message/BufferingMessage.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (C) 2019 Neil C Smith
  * Copyright (C) 2008 Wayne Meissner
  * Copyright (C) 2004 Wim Taymans <[email protected]>
  *
@@ -26,8 +27,13 @@
  * This message can be posted by an element that
  * needs to buffer data before it can continue processing. {@code percent} should be a
  * value between 0 and 100. A value of 100 means that the buffering completed.
- *
- * When <tt>percent}</tt> is &lt; 100 the application should PAUSE a PLAYING pipeline. When
+ * <p>
+ * See upstream documentation
+ * at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-buffering"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-buffering</a>
+ * <p>
+ * When <tt>percent</tt> is &lt; 100 the application should PAUSE a PLAYING pipeline. When
  * <tt>percent</tt> is 100, the application can set the pipeline (back) to PLAYING.
  * The application must be prepared to receive BUFFERING messages in the
  * PREROLLING state and may only set the pipeline to PLAYING after receiving a
@@ -40,13 +46,14 @@ public class BufferingMessage extends Message {
      * Creates a new Buffering message.
      * @param init internal initialization data.
      */
-    public BufferingMessage(Initializer init) {
+    BufferingMessage(Initializer init) {
         super(init);
     }
 
     /**
      * Creates a new Buffering message.
      * @param src The object originating the message.
+     * @param percent The buffering percent
      */
     public BufferingMessage(GstObject src, int percent) {
         this(initializer(GSTMESSAGE_API.ptr_gst_message_new_buffering(src, percent)));

src/org/freedesktop/gstreamer/message/DurationChangedMessage.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (C) 2019 Neil C Smith
  * Copyright (C) 2008 Wayne Meissner
  * Copyright (C) 2004 Wim Taymans <[email protected]>
  *
@@ -16,27 +17,37 @@
  * 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.message;
 
 import org.freedesktop.gstreamer.GstObject;
 import static org.freedesktop.gstreamer.lowlevel.GstMessageAPI.GSTMESSAGE_API;
 
 /**
- * The duration of a pipeline has changed. The application can get the new 
- * duration with a duration query.
+ * A duration changed message.
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-duration-changed"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-duration-changed</a>
+ * <p>
+ * This message is posted by elements that know the duration of a stream when
+ * the duration changes. This message is received by bins and is used to
+ * calculate the total duration of a pipeline.
  */
 public class DurationChangedMessage extends Message {
+
     /**
      * Creates a new DurationChanged message.
+     *
      * @param init internal initialization data.
      */
-    public DurationChangedMessage(Initializer init) {
+    DurationChangedMessage(Initializer init) {
         super(init);
     }
-    
+
     /**
      * Creates a new DurationChanged Message
+     *
+     * @param src The object originating the message.
      */
     public DurationChangedMessage(GstObject src) {
         this(initializer(GSTMESSAGE_API.ptr_gst_message_new_duration_changed(src)));

src/org/freedesktop/gstreamer/message/EOSMessage.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (C) 2019 Neil C Smith
  * Copyright (C) 2008 Wayne Meissner
  * Copyright (C) 2004 Wim Taymans <[email protected]>
  *
@@ -16,29 +17,37 @@
  * 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.message;
 
+import org.freedesktop.gstreamer.Bin;
 import org.freedesktop.gstreamer.GstObject;
 import static org.freedesktop.gstreamer.lowlevel.GstMessageAPI.GSTMESSAGE_API;
 
 /**
- * This message is generated and posted in the sink elements of a {@link org.freedesktop.gstreamer.Bin}.
- * The bin will only forward the EOS message to the application if all sinks 
+ * An End-of-Stream Message.
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-eos"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-eos</a>
+ * <p>
+ * This message is generated and posted in the sink elements of a {@link Bin}.
+ * The bin will only forward the EOS message to the application if all sinks
  * have posted an EOS message.
  */
 public class EOSMessage extends Message {
 
     /**
      * Creates a new eos message.
+     *
      * @param init internal initialization data.
      */
-    public EOSMessage(Initializer init) {
+    EOSMessage(Initializer init) {
         super(init);
     }
-    
+
     /**
      * Creates a new eos message.
+     *
      * @param src The object originating the message.
      */
     public EOSMessage(GstObject src) {

src/org/freedesktop/gstreamer/message/ErrorMessage.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (C) 2019 Neil C Smith
  * Copyright (C) 2008 Wayne Meissner
  * Copyright (C) 2004 Wim Taymans <[email protected]>
  *
@@ -25,6 +26,10 @@
 /**
  * This message is posted by element when a fatal event occurs.  
  * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-error"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-error</a>
+ * <p>
  * The pipeline will probably (partially) stop. The application
  * receiving this message should stop the pipeline.
  */
@@ -35,7 +40,7 @@ public class ErrorMessage extends GErrorMessage {
      * 
      * @param init internal initialization data.
      */
-    public ErrorMessage(Initializer init) {
+    ErrorMessage(Initializer init) {
         super(init);
     }
 

src/org/freedesktop/gstreamer/message/GErrorMessage.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (C) 2019 Neil C Smith
  * Copyright (C) 2008 Wayne Meissner
  *
  * This file is part of gstreamer-java.
@@ -24,9 +25,9 @@
 import static org.freedesktop.gstreamer.lowlevel.GlibAPI.GLIB_API;
 
 /**
- * Base class for ERROR, WARNING and INFO messages.
+ * Package private base class for ERROR, WARNING and INFO messages.
  */
-abstract public class GErrorMessage extends Message {
+abstract class GErrorMessage extends Message {
 
     /**
      * Creates a new GError message.
@@ -35,6 +36,7 @@ abstract public class GErrorMessage extends Message {
     GErrorMessage(Initializer init) {
         super(init);
     }
+    
     abstract GstAPI.GErrorStruct parseMessage();
 
     /**

src/org/freedesktop/gstreamer/message/InfoMessage.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (C) 2019 Neil C Smith
  * Copyright (C) 2008 Wayne Meissner
  * Copyright (C) 2004 Wim Taymans <[email protected]>
  *
@@ -16,34 +17,38 @@
  * 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.message;
 
 import org.freedesktop.gstreamer.lowlevel.GstAPI.GErrorStruct;
 import static org.freedesktop.gstreamer.lowlevel.GstMessageAPI.GSTMESSAGE_API;
 
 /**
  * This message is posted by element to provide information to the application.
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-info"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-info</a>
+ * <p>
  */
 public class InfoMessage extends GErrorMessage {
 
     /**
      * Creates a new info message.
-     * 
+     *
      * @param init internal initialization data.
      */
-    public InfoMessage(Initializer init) {
+    InfoMessage(Initializer init) {
         super(init);
     }
-    
+
     /**
      * Retrieves the GError structure contained in this message.
-     * 
+     *
      * @return the GError contained in this message.
      */
     @Override
     GErrorStruct parseMessage() {
-        GErrorStruct[] err = { null };
+        GErrorStruct[] err = {null};
         GSTMESSAGE_API.gst_message_parse_info(this, err, null);
         return err[0];
     }

src/org/freedesktop/gstreamer/message/LatencyMessage.java

@@ -1,4 +1,5 @@
 /* 
+ * Copyright (C) 2019 Neil C Smith
  * Copyright (C) 2008 Wayne Meissner
  * Copyright (C) 2004 Wim Taymans <[email protected]>
  *
@@ -16,28 +17,33 @@
  * 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.message;
 
 import org.freedesktop.gstreamer.GstObject;
 import static org.freedesktop.gstreamer.lowlevel.GstMessageAPI.GSTMESSAGE_API;
 
 /**
  * Message posted by elements when their latency requirements have changed.
+ * <p>
+ * See upstream documentation at
+ * <a href="https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-latency"
+ * >https://gstreamer.freedesktop.org/data/doc/gstreamer/stable/gstreamer/html/GstMessage.html#gst-message-new-latency</a>
+ * <p>
  */
 public class LatencyMessage extends Message {
+
     /**
      * Creates a new Latency message.
-     * 
+     *
      * @param init internal initialization data.
      */
-    public LatencyMessage(Initializer init) {
+    LatencyMessage(Initializer init) {
         super(init);
     }
-    
+
     /**
      * Creates a new Latency message.
-     * 
+     *
      * @param source the object originating the message.
      */
     public LatencyMessage(GstObject source) {