1340233 protect Dispatch constructor

1185167 Connect to running instance -- experimental API

src/com/jacob/activeX/ActiveXComponent.java

@@ -37,7 +37,8 @@ import com.jacob.com.*;
  * the senese that it is used for creating Dispatch objects
  */
 public class ActiveXComponent extends Dispatch {
-    /**
+
+	/**
      * Normally used to create a new connection to a microsoft application.
      * The passed in parameter is the name of the program as registred
      * in the registry.  It can also be the object name.
@@ -64,6 +65,14 @@ public class ActiveXComponent extends Dispatch {
         super(dispatchToBeWrapped);
     }
 
+    /**
+     * only used by the factories
+     *
+     */
+    private ActiveXComponent() {
+        super();
+    }
+
     /**
      * Probably was a cover for something else in the past.
      * Should be deprecated.
@@ -73,6 +82,64 @@ public class ActiveXComponent extends Dispatch {
         return this;
     }
 
+    /**
+     * Most code should use the standard ActiveXComponent(String) contructor
+     * and not this factory method.  This method exists for applications
+     * that need special behavior.
+     * <B>Experimental in release 1.9.2.</B> 
+     * <p>
+     * Factory that returns a Dispatch object wrapped around the result
+     * of a CoCreate() call. This differs from the standard constructor
+     * in that it throws no exceptions and returns null on failure.
+     * <p>
+     * This will fail for any prog id with a ":" in it.
+     *
+     * @param pRequestedProgramId
+     * @return Dispatch pointer to the COM object or null if couldn't create
+     */
+    public static ActiveXComponent createNewInstance(String pRequestedProgramId){
+    	ActiveXComponent mCreatedDispatch = null;
+    	try {
+    		mCreatedDispatch = new ActiveXComponent();
+    		mCreatedDispatch.coCreateInstanceJava(pRequestedProgramId);
+    	} catch (Exception e){
+    		mCreatedDispatch =null;
+    		if (JacobObject.isDebugEnabled()){
+    			JacobObject.debug("Unable to co-create instance of "+pRequestedProgramId);
+    		}
+    	}
+		return mCreatedDispatch;  
+    }
+    
+    /**
+     * Most code should use the standard ActiveXComponent(String) contructor
+     * and not this factory method.  This method exists for applications
+     * that need special behavior.
+     * <B>Experimental in release 1.9.2.</B> 
+     * <p>
+     * Factory that returns a Dispatch wrapped around the result
+     * of a getActiveObject() call.  This differs from the standard constructor
+     * in that it throws no exceptions and returns null on failure.
+     * <p>
+     * This will fail for any prog id with a ":" in it
+     * 
+     * @param pRequestedProgramId
+     * @return Dispatch pointer to a COM object or null if wasn't already running
+     */
+    public static ActiveXComponent connectToActiveInstance(String pRequestedProgramId){
+    	ActiveXComponent mCreatedDispatch = null;
+    	try {
+    		mCreatedDispatch = new ActiveXComponent();
+    		mCreatedDispatch.getActiveInstanceJava(pRequestedProgramId);
+    	} catch (Exception e){
+    		mCreatedDispatch =null;
+    		if (JacobObject.isDebugEnabled()){
+    			JacobObject.debug("Unable to attach to running instance of "+pRequestedProgramId);
+    		}
+    	}
+		return mCreatedDispatch;  
+    }
+    
     /**
      * @see com.jacob.com.Dispatch#finalize()
      */

src/com/jacob/com/Dispatch.java

@@ -150,11 +150,18 @@ public class Dispatch extends JacobObject
      * This constructor always creates a new windows/program object
      * because it is based on the CoCreate() windows function.  
      * <p>
+     * Fails silently if null is passed in as the program id
+     * <p>
      * @param requestedProgramId
      */
     public Dispatch(String requestedProgramId) {
         programId = requestedProgramId;
-        createInstance(requestedProgramId);
+        if (programId != null && !"".equals(programId)){
+        	createInstance(requestedProgramId);
+        } else {
+        	throw new IllegalArgumentException(
+        			"Dispatch(String) does not accept null or an empty string as a parameter");
+        }
     }
 
     /**
@@ -163,10 +170,59 @@ public class Dispatch extends JacobObject
      * Windows CoCreate() call
      * <P>
      * This ends up calling CoCreate down in the JNI layer
+     * <p>
+     * The behavior is different if a ":" character exists in the progId.  In that
+     * case CoGetObject and CreateInstance (someone needs to describe this better)
      * 
      * @param progid
      */
-    protected native void createInstance(String progid);
+    private native void createInstance(String progid);
+
+    /**
+     * native call getActiveInstance only used by the constructor with the same parm
+     * type. This probably should be private.  It is the wrapper for the
+     * Windows GetActiveObject() call
+     * <P>
+     * This ends up calling GetActiveObject down in the JNI layer
+     * <p>
+     * This does not have the special behavior for program ids with ":" in them
+     * that createInstance has. 
+     * 
+     * @param progid
+     */
+    private native void getActiveInstance(String progid);
+    
+    /**
+     * Wrapper around the native method
+     * @param progid
+     */
+    protected void getActiveInstanceJava(String progid){
+    	this.programId = progid;
+    	getActiveInstance(progid);
+    }
+
+    /**
+     * native call coCreateInstance only used by the constructor with the same parm
+     * type. This probably should be private.  It is the wrapper for the
+     * Windows CoCreate() call
+     * <P>
+     * This ends up calling CoCreate down in the JNI layer
+     * <p>
+     * This does not have the special behavior for program ids with ":" in them
+     * that createInstance has. 
+     * 
+     * @param progid
+     */
+    private native void coCreateInstance(String progid);
+
+    /**
+     * Wrapper around the native method
+     * @param progid
+     */
+    protected void coCreateInstanceJava(String progid){
+    	this.programId = progid;
+    	coCreateInstance(progid);
+    }
 
     /**
      * Return a different interface by IID string.