Experimental Applet without AWT (Applet3)

DISCLAIMER:
  - Only new Applet3 applets are supported under X11 for now

  - AWT Applet are disabled

  - Namespace com.jogamp.* and jogamp.* is only chosen
    to indicate new AWT-less code

  - Applet3 code path does not invoke any AWT function

  - JNLP code path still utilizes AWT/Swing (UIs, ..)

TODO:
  - Refactor AWT dependencies properly via UI interfaces ?

  - Decide whether we shall merge netx and plugin namespace ?
    IMHO the right thing to do, jumping hoops due to separation.

  - Add support for Windows, OSX, Wayland, ..

Applet3:

- New AWT-less Applet3 interfaces are:
  - com.jogamp.plugin.applet.Applet3
    - User implements

  - com.jogamp.plugin.applet.Applet3Context
    - Plugin implements

  - com.jogamp.plugin.ui.NativeWindowUpstream
    - Plugin window, aka browser parent of Applet3

  - com.jogamp.plugin.ui.NativeWindowDownstream
    - Applet3 user window

- User interfaces are exported as:
  - plugin3-public.jar
  - plugin3-public-src.zip

4 files changed, 393 insertions, 0 deletions

diff --git a/netx/com/jogamp/plugin/applet/Applet3.java b/netx/com/jogamp/plugin/applet/Applet3.java
new file mode 100644
index 0000000..b285852
--- /dev/null
+++ b/netx/com/jogamp/plugin/applet/Applet3.java
@@ -0,0 +1,150 @@
+/**
+ * Copyright 2014 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+package com.jogamp.plugin.applet;
+
+import java.util.Locale;
+
+import com.jogamp.plugin.ui.NativeWindowDownstream;
+import com.jogamp.plugin.ui.NativeWindowUpstream;
+
+/**
+ * Implemented by user.
+ * <a name="lifecycle"><h5>Applet3 Lifecycle</h5></a>
+ * <p>
+ * <ul>
+ *   <li>{@link #createNativeWindow(Applet3Context, NativeWindowUpstream)}</li>
+ *   <li>{@link #init(Applet3Context)}</li>
+ *   <li>{@link #start()}</li>
+ *   <li>{@link #stop()}</li>
+ *   <li>{@link #destroy()}</li>
+ * </ul>
+ * </p>
+ */
+public interface Applet3 {
+
+    /**
+     * Returns applet information or <code>null</code>.
+     * <p>
+     * Implementation may utilize this method to
+     * return information about the author, version, and copyright of the applet.
+     * </p>
+     */
+    String getAppletInfo();
+
+    /**
+     * Returns a custom locale of the applet or <code>null</code>.
+     */
+    Locale getLocale();
+
+    /**
+     * Returns a description of parameters as used by this applet, or <code>null</code>.
+     * <p>
+     * The returned string array is arranged to
+     * contain the <code>name</code>, the <code>type</code>, and a <code>description</code>.
+     * Example:
+     * <pre>
+     * String pinfo[][] = {
+     *   {"gl_profile",       "GLProfile String", "The GLProfile to be used, i.e. GL2ES2"},
+     *   {"gl_swap_interval", "0-4",              "The swap interval for vertical sync, i.e. 0 or 1"},
+     *   {"gl_debug",         "boolean",          "Enable JOGL debugging"}
+     * };
+     * </pre>
+     */
+    String[][] getParameterInfo();
+
+    /**
+     * Implementation creates a native child window, allowing to be controlled by the plugin.
+     * <p>
+     * The applet's child window is destroyed by the plugin after it has called {@link #destroy()}.
+     * </p>
+     * <p>
+     * Note that the returned {@link NativeWindowDownstream} instance's {@link NativeWindowDownstream#getParent()}
+     * must match the given <code>parent</code> instance, otherwise the applet will be aborted.
+     * </p>
+     * <p>
+     * See <a href="#lifecycle">Applet Lifecycle</a>.
+     * </p>
+     * @param context the {@link Applet3Context}
+     * @param parent the parent {@link NativeWindowUpstream}, reflecting the plugin's native applet window.
+     * @return {@link NativeWindowDownstream} users native child window.
+     */
+    NativeWindowDownstream createNativeWindow(Applet3Context context, NativeWindowUpstream parent);
+
+    /**
+     * Initialize the applet. Implementation may allocate resources.
+     * <p>
+     * See <a href="#lifecycle">Applet Lifecycle</a>.
+     * </p>
+     *
+     * @see #createNativeWindow(Applet3Context, NativeWindowUpstream)
+     * @see #destroy()
+     * @see #start()
+     * @see #stop()
+     */
+    void init(Applet3Context context);
+
+    /**
+     * Start the applet.
+     * <p>
+     * See <a href="#lifecycle">Applet Lifecycle</a>.
+     * </p>
+     * @see #createNativeWindow(Applet3Context, NativeWindowUpstream)
+     * @see #destroy()
+     * @see #start()
+     * @see #stop()
+     */
+    void start();
+
+    /**
+     * Stop the applet.
+     * <p>
+     * See <a href="#lifecycle">Applet Lifecycle</a>.
+     * </p>
+     * @see #createNativeWindow(Applet3Context, NativeWindowUpstream)
+     * @see #destroy()
+     * @see #start()
+     * @see #stop()
+     */
+    void stop();
+
+    /**
+     * Destroy the applet and all it's resources. Implementation shall release resources as allocated via {@link #init(Applet3Context)}.
+     * <p>
+     * Note that the applet's child window {@link #createNativeWindow(Applet3Context, NativeWindowUpstream) created by this implementation}
+     * is still valid and may be destroyed here.
+     * </p>
+     * <p>
+     * See <a href="#lifecycle">Applet Lifecycle</a>.
+     * </p>
+     * @see #createNativeWindow(Applet3Context, NativeWindowUpstream)
+     * @see #destroy()
+     * @see #start()
+     * @see #stop()
+     */
+    void destroy();
+}
diff --git a/netx/com/jogamp/plugin/applet/Applet3Context.java b/netx/com/jogamp/plugin/applet/Applet3Context.java
new file mode 100644
index 0000000..04528e6
--- /dev/null
+++ b/netx/com/jogamp/plugin/applet/Applet3Context.java
@@ -0,0 +1,87 @@
+/**
+ * Copyright 2014 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+package com.jogamp.plugin.applet;
+
+import java.io.IOException;
+import java.io.InputStream;
+import java.net.URL;
+import java.util.Enumeration;
+import java.util.Iterator;
+
+/**
+ * Provided by Plugin implementation.
+ */
+public interface Applet3Context {
+    /**
+     * Returns the {@link Applet3} bound to this context
+     */
+    Applet3 getApplet();
+    
+    String getAppletName();
+    
+    boolean isActive();
+    String getParameter(String name);
+    URL getDocumentBase();
+    URL getCodeBase();
+    
+    /**
+     * Requests that this applet be resized.
+     *
+     * @param   width    the new requested width for the applet.
+     * @param   height   the new requested height for the applet.
+     */
+    void resize(int width, int height);
+
+    /**
+     * Returns the {@link Applet3Context} within this context domain,
+     * referenced by the document, codebase and the given <code>name</code>.
+     * <p> 
+     * The <code>name</code> can be set in the HTML tag by setting the <code>name</code> attribute.
+     * </p>
+     */
+    Applet3Context getAppletContext(String name);
+
+    /**
+     * Returns all {@link Applet3Context} within this context domain,
+     * referenced by the document and codebase. 
+     */
+    Enumeration<Applet3Context> getAllAppletContexts();
+    
+    void showDocument(URL url);
+
+    void showDocument(URL url, String target);
+
+    void showStatus(String status);
+
+    void setStream(String key, InputStream stream)throws IOException;
+
+    InputStream getStream(String key);
+
+    Iterator<String> getStreamKeys();
+
+}
diff --git a/netx/com/jogamp/plugin/ui/NativeWindowDownstream.java b/netx/com/jogamp/plugin/ui/NativeWindowDownstream.java
new file mode 100644
index 0000000..0846505
--- /dev/null
+++ b/netx/com/jogamp/plugin/ui/NativeWindowDownstream.java
@@ -0,0 +1,81 @@
+/**
+ * Copyright 2014 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+package com.jogamp.plugin.ui;
+
+/**
+ * Implemented by user.
+ * <p>
+ * Representing the user applet child window,
+ * which is controlled by the plugin.
+ * </p>
+ */
+public interface NativeWindowDownstream {
+    /**
+     * Destroys this window incl. releasing all related resources.
+     */
+    public void destroy();
+
+    /**
+     * @return The parent NativeWindow, or null if this NativeWindow is top level.
+     */
+    public NativeWindowUpstream getParent();
+
+    /**
+     * Returns the window handle for this applet. <P>
+     *
+     * The window handle shall reflect the platform one
+     * for all window related operations, e.g. open, close, resize. <P>
+     *
+     * On X11 this returns an entity of type Window. <BR>
+     * On Microsoft Windows this returns an entity of type HWND.
+     */
+    public long getWindowHandle();
+
+    /**
+     * Set size.
+     */
+    public void setSize(int width, int height);
+
+    /**
+     * Request focus.
+     */
+    public void requestFocus();
+
+    /**
+     * Set this NativeWindow visible state.
+     */
+    public void setVisible(boolean v);
+
+    /**
+     * Trigger asynchronous rendering of this display's content.
+     * <p>
+     * Method shall return immediately and not wait for result.
+     * </p>
+     */
+    public void display();
+}
diff --git a/netx/com/jogamp/plugin/ui/NativeWindowUpstream.java b/netx/com/jogamp/plugin/ui/NativeWindowUpstream.java
new file mode 100644
index 0000000..ccd42e0
--- /dev/null
+++ b/netx/com/jogamp/plugin/ui/NativeWindowUpstream.java
@@ -0,0 +1,75 @@
+/**
+ * Copyright 2014 JogAmp Community. All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without modification, are
+ * permitted provided that the following conditions are met:
+ *
+ *    1. Redistributions of source code must retain the above copyright notice, this list of
+ *       conditions and the following disclaimer.
+ *
+ *    2. Redistributions in binary form must reproduce the above copyright notice, this list
+ *       of conditions and the following disclaimer in the documentation and/or other materials
+ *       provided with the distribution.
+ *
+ * THIS SOFTWARE IS PROVIDED BY JogAmp Community ``AS IS'' AND ANY EXPRESS OR IMPLIED
+ * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND
+ * FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL JogAmp Community OR
+ * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+ * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON
+ * ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+ * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF
+ * ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+ *
+ * The views and conclusions contained in the software and documentation are those of the
+ * authors and should not be interpreted as representing official policies, either expressed
+ * or implied, of JogAmp Community.
+ */
+package com.jogamp.plugin.ui;
+
+/**
+ * Representing the plugin window, i.e. the user applet's parent window.
+ */
+public interface NativeWindowUpstream {
+    /**
+     * Returns the display connection for this NativeWindow,
+     * maybe <code>null</code> for default.
+     * <p>
+     * On X11 this returns the X11 display connection string, e.g. <code>:0.0</code>.<BR>
+     * </p>
+     */
+    public String getDisplayConnection();
+
+    /**
+     * Returns the screen index for this NativeWindow.
+     */
+    public int getScreenIndex();
+
+    /**
+     * Returns the window handle for this NativeWindow. <P>
+     *
+     * The window handle shall reflect the platform one
+     * for all window related operations, e.g. open, close, resize. <P>
+     *
+     * On X11 this returns an entity of type Window. <BR>
+     * On Microsoft Windows this returns an entity of type HWND.
+     */
+    public long getWindowHandle();
+
+    /**
+     * Returns the width of the client area excluding insets (window decorations).
+     * @return width of the client area
+     */
+    public int getWidth();
+
+    /**
+     * Returns the height of the client area excluding insets (window decorations).
+     * @return height of the client area
+     */
+    public int getHeight();
+
+    /**
+     * Notify plugin that the applet's window has been <i>updated</i>, e.g. rendered and swapped.
+     */
+    public void notifySurfaceUpdated(NativeWindowDownstream swappedWin);
+}