Revert bean part of "java: remove dead methods"

...34bcf9b498bccb5c924f4cec850ff15d88df6f07; bean is a client API, not dead
code.

Change-Id: Iea17b6306152b9a4f2968bed550a44917803d9ec

bean/Jar_officebean.mk

@@ -27,6 +27,7 @@ $(eval $(call gb_Jar_add_sourcefiles,officebean,\
 	bean/com/sun/star/beans/NativeConnection \
 	bean/com/sun/star/beans/NativeService \
 	bean/com/sun/star/beans/OfficeConnection \
+	bean/com/sun/star/beans/OfficeWindow \
 	bean/com/sun/star/comp/beans/ContainerFactory \
 	bean/com/sun/star/comp/beans/Controller \
 	bean/com/sun/star/comp/beans/Frame \

bean/com/sun/star/beans/ContainerFactory.java

@@ -18,6 +18,8 @@
 
 package com.sun.star.beans;
 
+import java.awt.Container;
+
 /**
  * This interface reprecents an AWT container factory.
  *
@@ -27,5 +29,10 @@ package com.sun.star.beans;
 
 public interface ContainerFactory
 {
-
+    /**
+     * Creates an AWT container.
+     *
+     * @return An AWT container.
+     */
+    Container createContainer();
 }

bean/com/sun/star/beans/LocalOfficeConnection.java

@@ -18,6 +18,7 @@
 
 package com.sun.star.beans;
 
+import java.awt.Container;
 import java.io.File;
 import java.util.Iterator;
 import java.util.List;
@@ -157,6 +158,19 @@ public class LocalOfficeConnection
         return mContext;
     }
 
+    /**
+     * Creates an office window.
+     * The window is either a sub-class of java.awt.Canvas (local) or
+     * java.awt.Container (RVP).
+     *
+     * @param container This is an AWT container.
+     * @return The office window instance.
+     */
+    public OfficeWindow createOfficeWindow(Container container)
+    {
+        return new LocalOfficeWindow(this);
+    }
+
     /**
      * Closes the connection.
      */

bean/com/sun/star/beans/LocalOfficeWindow.java

@@ -42,7 +42,7 @@ import com.sun.star.uno.XComponentContext;
  */
 public class LocalOfficeWindow
     extends java.awt.Canvas
-    implements XEventListener
+    implements OfficeWindow, XEventListener
 {
     private transient OfficeConnection  mConnection;
     private transient XWindowPeer       mParentProxy;

bean/com/sun/star/beans/OfficeConnection.java

@@ -20,6 +20,7 @@ package com.sun.star.beans;
 
 import com.sun.star.lang.XComponent;
 import com.sun.star.uno.XComponentContext;
+import java.awt.Container;
 
 /**
  * This abstract class reprecents a connection to the office
@@ -37,7 +38,13 @@ public interface OfficeConnection
     void setUnoUrl(String url)
         throws java.net.MalformedURLException;
 
-
+    /**
+     * Sets an AWT container catory.
+     *
+     * @param containerFactory This is a application provided AWT container
+     *  factory.
+     */
+    void setContainerFactory(ContainerFactory containerFactory);
 
     /**
      * Retrieves the UNO component context.
@@ -48,5 +55,15 @@ public interface OfficeConnection
      */
     XComponentContext getComponentContext();
 
-
+    /**
+     * Creates an office window.
+     * The window is either a sub-class of java.awt.Canvas (local) or
+     * java.awt.Container (RVP).
+     *
+     * This method does not add add the office window to its container.
+     *
+     * @param container This is an AWT container.
+     * @return The office window instance.
+     */
+    OfficeWindow createOfficeWindow(Container container);
 }

bean/com/sun/star/beans/OfficeWindow.java

@@ -0,0 +1,46 @@
+/*
+ * This file is part of the LibreOffice project.
+ *
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at http://mozilla.org/MPL/2.0/.
+ *
+ * This file incorporates work covered by the following license notice:
+ *
+ *   Licensed to the Apache Software Foundation (ASF) under one or more
+ *   contributor license agreements. See the NOTICE file distributed
+ *   with this work for additional information regarding copyright
+ *   ownership. The ASF licenses this file to you under the Apache
+ *   License, Version 2.0 (the "License"); you may not use this file
+ *   except in compliance with the License. You may obtain a copy of
+ *   the License at http://www.apache.org/licenses/LICENSE-2.0 .
+ */
+
+package com.sun.star.beans;
+
+import java.awt.Component;
+
+import com.sun.star.awt.XWindowPeer;
+
+/**
+ * The concreate implementation of the OfficeWindow extends an
+ * approperate type of visual component (java.awt.Canvas for local
+ * and java.awt.Container for remote).
+ * @deprecated
+ */
+public interface OfficeWindow
+{
+    /**
+     * Retrieves an AWT component object associated with the OfficeWindow.
+     *
+     * @return The AWT component object associated with the OfficeWindow.
+     */
+    Component getAWTComponent();
+
+    /**
+     * Retrieves an UNO XWindowPeer object associated with the OfficeWindow.
+     *
+     * @return The UNO XWindowPeer object associated with the OfficeWindow.
+     */
+    XWindowPeer getUNOWindowPeer();
+}

bean/com/sun/star/comp/beans/ContainerFactory.java

@@ -18,6 +18,8 @@
 
 package com.sun.star.comp.beans;
 
+import java.awt.Container;
+
 /**
  * This interface represents an AWT container factory.
  *
@@ -27,5 +29,10 @@ package com.sun.star.comp.beans;
 
 public interface ContainerFactory
 {
-
+    /**
+     * Creates an AWT container.
+     *
+     * @return An AWT container.
+     */
+    Container createContainer();
 }

bean/com/sun/star/comp/beans/Controller.java

@@ -83,7 +83,13 @@ public class Controller
     // com.sun.star.frame.XDispatchProvider
 
 
-
+    public com.sun.star.frame.XDispatch queryDispatch(
+            /*IN*/ com.sun.star.util.URL aURL,
+            /*IN*/ String aTargetFrameName,
+            /*IN*/ int nSearchFlags )
+    {
+        return xDispatchProvider.queryDispatch( aURL, aTargetFrameName, nSearchFlags );
+    }
 
     public com.sun.star.frame.XDispatch[] queryDispatches(
             /*IN*/ com.sun.star.frame.DispatchDescriptor[] aRequests )

bean/com/sun/star/comp/beans/OOoBean.java

@@ -181,7 +181,25 @@ public class OOoBean
         xConnectionListener = this.new EventListener("setOOoConnection");
     }
 
+    // @requirement FUNC.CON.STRT/0.4
+    /** Starts a connection to an OOo instance which is lauched if not running.
 
+        @throws HasConnectionException
+            if a connection was already established.
+
+        @throws NoConnectionException
+            if the specified connection cannot be established
+     */
+    public void startOOoConnection( String aConnectionURL )
+        throws  java.net.MalformedURLException,
+            HasConnectionException,
+            NoConnectionException
+    {
+        // create a new connection from the given connection URL
+        LocalOfficeConnection aConnection = new LocalOfficeConnection();
+        aConnection.setUnoUrl( aConnectionURL );
+        setOOoConnection( aConnection );
+    }
 
     // @requirement FUNC.CON.CHK/0.7
     /** Returns true if this OOoBean is connected to an OOo instance,
@@ -313,7 +331,31 @@ public class OOoBean
         return xDesktop;
     }
 
+    /** Resets this bean to an empty document.
 
+       If a document is loaded and the content modified,
+       the changes are dismissed.  Otherwise nothing happens.
+
+       This method is intended to be overridden in derived classes.
+       This implementation simply calls clear.
+
+       @param bClearStateToo
+           Not only the document content but also the state of the bean,
+        like visibility of child components is cleared.
+
+        @deprecated There is currently no way to dismiss changes, except for loading
+        of the unchanged initial document. Furthermore it is unclear how derived classes
+        handle this and what exactly their state is (e.g. what members make up their state).
+        Calling this method on a derived class requires knowledge about their implementation.
+        Therefore a deriving class should declare their own clearDocument if needed. Clients
+        should call the clearDocument of the deriving class or {@link #clear} which discards
+        the currently displayed document.
+     */
+    public synchronized void clearDocument( boolean bClearStateToo )
+    {
+        // TBD
+        clear();
+    }
 
     /** Resets the OOoBean to an empty status.
 
@@ -654,9 +696,219 @@ public class OOoBean
         }
     }
 
+    /** Loads a document from a Java stream.
 
+           See loadFromURL() for further information.
+     */
+    public void loadFromStream(
+            final java.io.InputStream iInStream,
+            final com.sun.star.beans.PropertyValue aArguments[] )
+        throws
+            // @requirement FUNC.CON.LOST/0.2
+            NoConnectionException,
+            java.io.IOException,
+            com.sun.star.lang.IllegalArgumentException,
+            com.sun.star.util.CloseVetoException
+    {
+        // wrap Java stream into UNO stream
 
+                 // copy stream....
+                 int s = 4096;
+                 int r=0 ,n = 0;
+                 byte[] buffer = new byte[s];
+                 byte[] newBuffer = null;
+                 while ((r = iInStream.read(buffer, n, buffer.length-n))>0) {
+                     n += r;
+                     if (iInStream.available() > buffer.length - n) {
+                         newBuffer = new byte[buffer.length*2];
+                         System.arraycopy(buffer, 0, newBuffer, 0, n);
+                         buffer = newBuffer;
+                     }
+                }
+                if (buffer.length != n) {
+                    newBuffer = new byte[n];
+                    System.arraycopy(buffer, 0, newBuffer, 0, n);
+                    buffer = newBuffer;
+                }
+                com.sun.star.io.XInputStream xStream =
+                    new com.sun.star.lib.uno.adapter.ByteArrayToXInputStreamAdapter(buffer);
 
+        // add stream to arguments
+        com.sun.star.beans.PropertyValue[] aExtendedArguments =
+            addArgument( aArguments, new com.sun.star.beans.PropertyValue(
+                "InputStream", -1, xStream, com.sun.star.beans.PropertyState.DIRECT_VALUE ) );
+
+        // call normal load method
+        loadFromURL( "private:stream", aExtendedArguments );
+    }
+
+    /** Loads a document from a byte array.
+
+           See loadFromURL() for further information.
+     */
+    public void loadFromByteArray(
+            final byte aInBuffer[],
+            final com.sun.star.beans.PropertyValue aArguments[] )
+        throws
+            // @requirement FUNC.CON.LOST/0.2
+            NoConnectionException,
+            java.io.IOException,
+            com.sun.star.lang.IllegalArgumentException,
+            com.sun.star.util.CloseVetoException
+    {
+        // wrap byte arrray into UNO stream
+        com.sun.star.io.XInputStream xStream =
+                new com.sun.star.lib.uno.adapter.ByteArrayToXInputStreamAdapter(
+                    aInBuffer );
+
+        // add stream to arguments
+        com.sun.star.beans.PropertyValue[] aExtendedArguments =
+            addArgument( aArguments, new com.sun.star.beans.PropertyValue(
+                "InputStream", -1, xStream, com.sun.star.beans.PropertyState.DIRECT_VALUE ) );
+
+        // call normal load method
+        loadFromURL( "private:stream", aExtendedArguments );
+    }
+
+    /** Stores a document to the given URL.
+        <p>
+        Due due a bug (50651) calling this method may cause the office to crash,
+        when at the same time the office writes a backup of the document. This bug
+        also affects {@link #storeToByteArray storeToByteArray} and
+        {@link #storeToStream storeToStream}. The workaround
+        is to start the office with the option --norestore, which disables the automatic
+        backup and recovery mechanism. OOoBean offers currently no supported way of providing
+        startup options for OOo. But it is possible to set a Java property when starting
+        Java, which is examined by OOoBean:
+        <pre>
+            java -Dcom.sun.star.officebean.Options=--norestore  ...
+        </pre>
+        It is planned to offer a way of specifying startup options in a future version.
+        The property can be used until then. When using this property only one option
+        can be provided.
+
+        @throws IllegalArgumentException
+            if either of the arguments is out of the specified range.
+
+        @throws java.io.IOException
+            if an IO error occurs reading the resource specified by the URL.
+
+        @throws com.sun.star.lang.NoConnectionException
+            if no connection is established.
+
+        @throws NoDocumentException
+            if no document is loaded
+     */
+    private void storeToURL(
+            final String aURL,
+            final com.sun.star.beans.PropertyValue aArguments[] )
+        throws
+            // @requirement FUNC.CON.LOST/0.2
+            NoConnectionException,
+            java.io.IOException,
+            com.sun.star.lang.IllegalArgumentException,
+            NoDocumentException
+    {
+        // no document available?
+        if ( aDocument == null )
+            throw new NoDocumentException();
+
+        try
+        {
+            // start runtime timeout
+            CallWatchThread aCallWatchThread =
+                new CallWatchThread( nOOoCallTimeOut, "storeToURL" );
+
+            // store the document
+            try { aDocument.storeToURL( aURL, aArguments ); }
+            catch ( com.sun.star.io.IOException aExc )
+            { throw new java.io.IOException(); }
+
+            // end runtime timeout
+            aCallWatchThread.cancel();
+        }
+        catch ( java.lang.InterruptedException aExc )
+        { throw new NoConnectionException(); }
+    }
+
+    /** Stores a document to a stream.
+
+           See {@link #storeToURL storeToURL} for further information.
+        @see #storeToURL storeToURL
+     */
+    public java.io.OutputStream storeToStream(
+            java.io.OutputStream aOutStream,
+            final com.sun.star.beans.PropertyValue aArguments[] )
+        throws
+            // @requirement FUNC.CON.LOST/0.2
+            NoConnectionException,
+            NoDocumentException,
+            java.io.IOException,
+            com.sun.star.lang.IllegalArgumentException
+
+    {
+        // wrap Java stream into UNO stream
+        com.sun.star.lib.uno.adapter.OutputStreamToXOutputStreamAdapter aStream =
+                new com.sun.star.lib.uno.adapter.OutputStreamToXOutputStreamAdapter(
+                    aOutStream );
+
+        // add stream to arguments
+        com.sun.star.beans.PropertyValue[] aExtendedArguments =
+            addArgument( aArguments, new com.sun.star.beans.PropertyValue(
+                "OutputStream", -1, aStream, com.sun.star.beans.PropertyState.DIRECT_VALUE ) );
+
+        // call normal store method
+        storeToURL( "private:stream", aExtendedArguments );
+
+        // get byte array from document stream
+        try { aStream.closeOutput(); }
+        catch ( com.sun.star.io.NotConnectedException aExc )
+        { /* TDB */ }
+        catch ( com.sun.star.io.BufferSizeExceededException aExc )
+        { /* TDB */ }
+        catch ( com.sun.star.io.IOException aExc )
+        { throw new java.io.IOException(); }
+        return aOutStream;
+    }
+
+    /** Stores a document to a byte array.
+
+           See {@link #storeToURL storeToURL} for further information.
+        @see #storeToURL storeToURL
+     */
+    public byte[] storeToByteArray(
+            byte aOutBuffer[],
+            final com.sun.star.beans.PropertyValue aArguments[] )
+        throws
+            // @requirement FUNC.CON.LOST/0.2
+            NoConnectionException,
+            NoDocumentException,
+            java.io.IOException,
+            com.sun.star.lang.IllegalArgumentException
+    {
+        // wrap byte arrray into UNO stream
+        com.sun.star.lib.uno.adapter.XOutputStreamToByteArrayAdapter aStream =
+                new com.sun.star.lib.uno.adapter.XOutputStreamToByteArrayAdapter(
+                    aOutBuffer );
+
+        // add stream to arguments
+        com.sun.star.beans.PropertyValue[] aExtendedArguments =
+            addArgument( aArguments, new com.sun.star.beans.PropertyValue(
+                "OutputStream", -1, aStream, com.sun.star.beans.PropertyState.DIRECT_VALUE ) );
+
+        // call normal store method
+        storeToURL( "private:stream", aExtendedArguments );
+
+        // get byte array from document stream
+        try { aStream.closeOutput(); }
+        catch ( com.sun.star.io.NotConnectedException aExc )
+        { /* TDB */ }
+        catch ( com.sun.star.io.BufferSizeExceededException aExc )
+        { /* TDB */ }
+        catch ( com.sun.star.io.IOException aExc )
+        { throw new java.io.IOException(); }
+        return aStream.getBuffer();
+    }
 
     // @requirement FUNC.BEAN.PROG/0.5
     // @requirement API.SIM.SEAP/0.2

bean/com/sun/star/comp/beans/OfficeConnection.java

@@ -40,7 +40,13 @@ public interface OfficeConnection
     void setUnoUrl(String url)
         throws java.net.MalformedURLException;
 
-
+    /**
+     * Sets an AWT container catory.
+     *
+     * @param containerFactory This is a application provided AWT container
+     *  factory.
+     */
+    void setContainerFactory(ContainerFactory containerFactory);
 
     /**
      * Retrieves the UNO component context.