Com4jObject


1   package com4j;
2   
3   /**
4    * Root of all the com4j interfaces.
5    *
6    * <p>
7    * Java interfaces mapped from COM interfaces always derive from this
8    * interface directly/indirectly. This interface provides methods
9    * that are common to all the COM interfaces.
10   *
11   * @author Kohsuke Kawaguchi (kk@kohsuke.org)
12   */
13  @IID("{00000000-0000-0000-C000-000000000046}")
14  public interface Com4jObject {
15      /**
16       * Tests the identity of two COM objects.
17       *
18       * <p>
19       * This consists of doing <tt>IUnknown::QueryInterface</tt> on
20       * two interfaces and test the bit image of the resulting <tt>IUnknown*</tt>.
21       *
22       * <p>
23       * If one COM object implements two interfaces, in Java
24       * you see them as two different objects. Thus you
25       * cannot rely on <tt>==</tt> to check if they represent
26       * the same COM object.
27       */
28      boolean equals(Object   o);
29  
30      /**
31       * Hash code consistent with {@link #equals(java.lang.Object)} }.
32       *
33       * <p>
34       * This method queries the <tt>IUnknown*</tt> value to the wrapped
35       * COM object and returns its pointer bit image as integer.
36       *
37       * <p>
38       * The net result is that the identity of {@link Com4jObject} is based
39       * on the identity of the underlying COM objects. Two {@link Com4jObject}
40       * that are holding different interfaces of the same COM object is
41       * considered "equal".
42       */
43      int hashCode();
44  
45      /**
46       * Prints the raw interface pointer that this object represents.
47       */
48      String   toString();
49  
50      /**
51       * Releases a reference to the wrapped COM object.
52       *
53       * <p>
54       * Since Java objects tend to live longer in memory until it's GC-ed,
55       * and applications have generally no control over when it's GC-ed,
56       * calling the dispose method earlier enables applications to dispose
57       * the COM objects deterministically.
58       */
59      void dispose();
60  
61      /**
62       * Checks if this COM object implements a given interface.
63       *
64       * <p>
65       * This is just a convenience method that behaves as follows:
66       * <pre>
67       * return queryInterface(comInterface)!=null;
68       * </pre>
69       *
70       * @return
71       *      true if the wrapped COM object implements a given interface.
72       */
73      <T extends Com4jObject> boolean is( Class  <T> comInterface );
74  
75      /**
76       * Invokes the queryInterface of the wrapped COM object and attempts
77       * to obtain a different interface of the same object.
78       *
79       * @return null
80       *      if the queryInterface fails.
81       */
82      <T extends Com4jObject> T queryInterface( Class  <T> comInterface );
83  }
84
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags