#96701# API review

jurt/com/sun/star/uno/AnyConverter.java

@@ -9,50 +9,99 @@ import com.sun.star.lang.IllegalArgumentException;
  */
 public class AnyConverter
 {
+    /** checks if the any contains the idl type <code>void</code>.
+        @param object the object to check
+        @return true when the any is void, false otherwise
+     */
     static public boolean isVoid( Object object){
         return containsType( TypeClass.VOID, object);
     }
 
+    /** checks if the any contains a value of the idl type <code>char</code>.
+        @param object the object to check
+        @return true when the any contains a char, false otherwise.
+     */
     static public boolean isChar(Object object){
         return containsType( TypeClass.CHAR, object);
     }
 
+    /** checks if the any contains a value of the idl type <code>boolean</code>.
+        @param object the object to check
+        @return true when the any contains a boolean, false otherwise.
+     */
     static public boolean isBoolean(Object object){
         return containsType( TypeClass.BOOLEAN, object);
     }
 
+    /** checks if the any contains a value of the idl type <code>byte</code>.
+        @param object the object to check
+        @return true when the any contains a byte, false otherwise.
+     */
     static public boolean isByte(Object object){
         return containsType( TypeClass.BYTE, object);
     }
 
+    /** checks if the any contains a value of the idl type <code>short</code>.
+        @param object the object to check
+        @return true when the any contains a short, false otherwise.
+     */
     static public boolean isShort(Object object){
         return containsType( TypeClass.SHORT, object);
     }
 
+    /** checks if the any contains a value of the idl type <code>long</code> (which maps to a java-int).
+        @param object the object to check
+        @return true when the any contains a int, false otherwise.
+     */
     static public boolean isInt(Object object){
         return containsType( TypeClass.LONG, object);
     }
 
+    /** checks if the any contains a value of the idl type <code>hyper</code> (which maps to a java-long).
+        @param object the object to check
+        @return true when the any contains a long, false otherwise.
+     */
     static public boolean isLong(Object object){
         return containsType( TypeClass.HYPER, object);
     }
 
+    /** checks if the any contains a value of the idl type <code>float</code>.
+        @param object the object to check
+        @return true when the any contains a float, false otherwise.
+     */
     static public boolean isFloat(Object object){
         return containsType( TypeClass.FLOAT, object);
     }
 
+    /** checks if the any contains a value of the idl type <code>double</code>.
+        @param object the object to check
+        @return true when the any contains a double, false otherwise.
+     */
     static public boolean isDouble(Object object){
         return containsType( TypeClass.DOUBLE, object);
     }
 
+    /** checks if the any contains a value of the idl type <code>string</code>.
+        @param object the object to check
+        @return true when the any contains a string, false otherwise.
+     */
     static public boolean isString(Object object){
         return containsType( TypeClass.STRING, object);
     }
 
+
+    /** checks if the any contains a value of the idl type <code>type</code>.
+        @param object the object to check
+        @return true when the any contains a type, false otherwise.
+     */
     static public boolean isType(Object object){
         return containsType( TypeClass.TYPE, object);
     }
 
+    /** checks if the any contains a value which implements interfaces.
+        @param object the object to check
+        @return true when the any contains an object which implements interfaces, false otherwise.
+     */
     static public boolean isObject(Object object){
         boolean retVal= false;
         if( object.getClass().getInterfaces().length > 0)
@@ -70,73 +119,139 @@ public class AnyConverter
         return retVal;
     }
 
+    /** checks if the any contains UNO idl sequence value ( meaning a java array
+        containing elements which are values of UNO idl types).
+        @param object the object to check
+        @return true when the any contains an object which implements interfaces, false otherwise.
+     */
     static public boolean isArray( Object object){
         return containsType( TypeClass.SEQUENCE, object);
     }
 
+    /** converts an Char object or an Any object containing a Char object into a simple char.
+        @param object the object to convert
+        @return the char contained within the object
+        @throws com.sun.star.lang.IllegalArgumentException in case no char is contained within object
+        @see #isChar
+    */
     static public char  toChar(Object object) throws  com.sun.star.lang.IllegalArgumentException{
         Character ret=(Character) convertSimple( TypeClass.CHAR, null, object);
         return ret.charValue();
     }
 
+    /** converts an Boolean object or an Any object containing a Boolean object into a simple boolean.
+        @param object the object to convert
+        @return the boolean contained within the object
+        @throws com.sun.star.lang.IllegalArgumentException in case no boolean is contained within object
+        @see #isBoolean
+    */
     static public boolean toBoolean(Object object) throws  com.sun.star.lang.IllegalArgumentException{
         Boolean ret= (Boolean)  convertSimple( TypeClass.BOOLEAN, null, object);
         return ret.booleanValue();
     }
 
+    /** converts an Byte object or an Any object containing a Byte object into a simple byte.
+        @param object the object to convert
+        @return the boolean contained within the object
+        @throws com.sun.star.lang.IllegalArgumentException in case no byte is contained within object
+        @see #isBoolean
+    */
     static public byte toByte(Object object) throws   com.sun.star.lang.IllegalArgumentException{
         Byte ret= (Byte) convertSimple( TypeClass.BYTE, null, object);
         return ret.byteValue();
     }
 
-        /** Allowed argument types are Byte, Short or Any containing these types.
+    /** converts a number object into a simple short and allows widening conversions.
-         */
+        Allowed argument types are Byte, Short or Any containing these types.
+        @param object the object to convert
+        @throws com.sun.star.lang.IllegalArgumentException in case no short or byte is contained within object
+        @return the short contained within the object
+     */
     static public short toShort(Object object) throws   com.sun.star.lang.IllegalArgumentException{
         Short ret= (Short) convertSimple( TypeClass.SHORT, null, object);
         return ret.shortValue();
     }
 
-        /** Allowed argument types are Byte, Short, Integer or Any containing these types.
+    /** converts a number object into a simple int and allows widening conversions.
-         */
+        Allowed argument types are Byte, Short, Integer or Any containing these types.
+        @param object the object to convert
+        @throws com.sun.star.lang.IllegalArgumentException in case no short, byte or int is contained within object.
+        @return the int contained within the object
+     */
     static public int toInt(Object object) throws  com.sun.star.lang.IllegalArgumentException{
         Integer ret= (Integer) convertSimple( TypeClass.LONG, null, object);
         return ret.intValue();
     }
 
-        /** Allowed argument types are Byte, Short, Integer, Long or Any containing these types.
+    /** converts a number object into a simple long and allows widening conversions.
-         */
+        Allowed argument types are Byte, Short, Integer, Long or Any containing these types.
+        @param object the object to convert
+        @throws com.sun.star.lang.IllegalArgumentException in case no short, byte, int or long
+                is contained within object.
+        @return the long contained within the object
+     */
     static public long toLong(Object object) throws   com.sun.star.lang.IllegalArgumentException{
         Long ret= (Long) convertSimple( TypeClass.HYPER, null, object);
         return ret.longValue();
     }
 
-        /** Allowed argument types are Byte, Short, Float or Any containing these types.
+    /** converts a number object into a simple float and allows widening conversions.
-         */
+        Allowed argument types are Byte, Short, Float or Any containing these types.
+        @param object the object to convert
+        @throws com.sun.star.lang.IllegalArgumentException in case no byte, short or float
+                is contained within object.
+        @return the float contained within the object
+     */
     static public float toFloat(Object object) throws com.sun.star.lang.IllegalArgumentException{
         Float ret= (Float) convertSimple( TypeClass.FLOAT,null, object);
         return ret.floatValue();
     }
 
-        /** Allowed argument types are Byte, Short, Integer, Float, Double or Any containing these types.
+    /** converts a number object into a simple double and allows widening conversions.
-         */
+        Allowed argument types are Byte, Short, Int, Float, Double or Any containing these types.
+        @param object the object to convert
+        @throws com.sun.star.lang.IllegalArgumentException in case no byte, short, int, float
+                or double is contained within object.
+        @return the double contained within the object
+     */
     static public double toDouble(Object object) throws com.sun.star.lang.IllegalArgumentException {
         Double ret= (Double) convertSimple( TypeClass.DOUBLE, null, object);
         return ret.doubleValue();
     }
 
+    /** converts a string or an any containing a string into a string.
+        @param object the object to convert
+        @throws com.sun.star.lang.IllegalArgumentException in case no string is contained within object.
+        @return the string contained within the object
+     */
     static public String toString(Object object) throws com.sun.star.lang.IllegalArgumentException {
         return (String) convertSimple( TypeClass.STRING, null, object);
     }
 
+    /** converts a Type or an any containing a Type into a Type.
+        @param object the object to convert
+        @throws com.sun.star.lang.IllegalArgumentException in case no type is contained within object.
+        @return the type contained within the object
+     */
     static public Type toType(Object object) throws com.sun.star.lang.IllegalArgumentException {
         return (Type) convertSimple( TypeClass.TYPE, null, object);
     }
 
+    /** converts a UNO object an any containing a UNO object into a UNO object.
+        @param object the object to convert
+        @throws com.sun.star.lang.IllegalArgumentException in case no UNO object is contained within object.
+        @return the object contained within the object
+     */
     static public Object toObject(Type type, Object object)
         throws com.sun.star.lang.IllegalArgumentException{
         return convertSimple( TypeClass.ANY,  type, object);
     }
 
+    /** converts an array or an any containing an array into an array.
+        @param object the object to convert
+        @throws com.sun.star.lang.IllegalArgumentException in case no array is contained within object.
+        @return the array contained within the object
+     */
     static public Object toArray( Object object) throws com.sun.star.lang.IllegalArgumentException {
         return convertSimple( TypeClass.SEQUENCE, null, object);
     }

jurt/com/sun/star/uno/Ascii.java

@@ -2,9 +2,9 @@
  *
  *  $RCSfile: Ascii.java,v $
  *
- *  $Revision: 1.1.1.1 $
+ *  $Revision: 1.2 $
  *
- *  last change: $Author: hr $ $Date: 2000-09-18 15:27:53 $
+ *  last change: $Author: jbu $ $Date: 2002-01-18 14:06:54 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -64,9 +64,10 @@ package com.sun.star.uno;
 /**
  * The Ascii class represents the IDL build in type <code>ascii</code>.
  * <p>
- * @version     $Revision: 1.1.1.1 $ $ $Date: 2000-09-18 15:27:53 $
+ * @version     $Revision: 1.2 $ $ $Date: 2002-01-18 14:06:54 $
  * @author      Markus Meyer
  * @since       UDK1.0
+ * @deprecated do not use
  */
 public final class Ascii {
     public final char ascii;
@@ -74,6 +75,7 @@ public final class Ascii {
     /**
      * Constructs a new <code>Ascii</code>.
      * <p>
+     * @deprecated do not use
      * @param   c  the char value
      */
     public Ascii(char c) {

jurt/com/sun/star/uno/AsciiString.java

@@ -2,9 +2,9 @@
  *
  *  $RCSfile: AsciiString.java,v $
  *
- *  $Revision: 1.1.1.1 $
+ *  $Revision: 1.2 $
  *
- *  last change: $Author: hr $ $Date: 2000-09-18 15:27:54 $
+ *  last change: $Author: jbu $ $Date: 2002-01-18 14:06:54 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -64,9 +64,10 @@ package com.sun.star.uno;
 /**
  * The Ascii class represents the IDL build in type <code>asciistring</code>.
  * <p>
- * @version     $Revision: 1.1.1.1 $ $ $Date: 2000-09-18 15:27:54 $
+ * @version     $Revision: 1.2 $ $ $Date: 2002-01-18 14:06:54 $
  * @author      Markus Meyer
  * @since       UDK1.0
+ * @deprecated do not use
  */
 public final class AsciiString {
     public final String asciistring;
@@ -74,6 +75,7 @@ public final class AsciiString {
     /**
      * Constructs a new <code>AsciiString</code>.
      * <p>
+     * @deprecated do not use
      * @param   s  the String value
      */
     public AsciiString(String s) {

jurt/com/sun/star/uno/MappingException.java

@@ -2,9 +2,9 @@
  *
  *  $RCSfile: MappingException.java,v $
  *
- *  $Revision: 1.1.1.1 $
+ *  $Revision: 1.2 $
  *
- *  last change: $Author: hr $ $Date: 2000-09-18 15:27:54 $
+ *  last change: $Author: jbu $ $Date: 2002-01-18 14:06:54 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -65,8 +65,7 @@ package com.sun.star.uno;
 /**
  * The mapping Exception.
  * <p>
- * @version     $Revision: 1.1.1.1 $ $ $Date: 2000-09-18 15:27:54 $
+ * @version     $Revision: 1.2 $ $ $Date: 2002-01-18 14:06:54 $
- * @author      Kay Ramme
  * @see         com.sun.star.uno.UnoRuntime
  * @see         com.sun.star.uno.IQueryInterface
  * @see         com.sun.star.uno.IBridge

ridljar/com/sun/star/uno/Any.java

@@ -2,9 +2,9 @@
  *
  *  $RCSfile: Any.java,v $
  *
- *  $Revision: 1.3 $
+ *  $Revision: 1.4 $
  *
- *  last change: $Author: kr $ $Date: 2001-05-08 09:34:18 $
+ *  last change: $Author: jbu $ $Date: 2002-01-18 14:04:55 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -65,17 +65,21 @@ package com.sun.star.uno;
 
 /**
  * The UNO IDL type any is mapped to java type <code>java.lang.Object</code>.
- * In special cases it is necessary to have an explicit any.
  * <p>
- * @version     $Revision: 1.3 $ $ $Date: 2001-05-08 09:34:18 $
+ * In special cases it is necessary to have an explicit any to additionally transport
- * @author      Kay Ramme
+ * an exact type. For instance if you want to pass an object reference via
+ * an interprocess connection using an any, you should use this class to add
+ * an explicit interface type, so the remote counterpart doesn't need to invoke
+ * a queryInterface).
+ * <p>
+ * @version     $Revision: 1.4 $ $ $Date: 2002-01-18 14:04:55 $
  * @since       UDK1.0
  */
 public class Any {
     /**
      * The type of the any.
      * <p>
-     * @see #getInterface
+     * @see #getType
      */
     protected Type  _type;
 
@@ -99,24 +103,28 @@ public class Any {
         _object = object;
     }
 
+    /** Constructs a new any with a given type and value
+        @param type the UNO type of the any.
+        @param object the value of the any.
+     */
     public Any(Type type, Object object) {
         _type   = type;
         _object = object;
     }
 
     /**
-     * Gets the type of the any.
+     * Gets the type of the value within the any.
      * <p>
-     * @return   the type of the any.
+     * @return   the type of the value within the any.
      */
     public Type getType() {
         return _type;
     }
 
     /**
-     * Gets the data of the any.
+     * Gets the value within the any.
      * <p>
-     * @return   the data of the any.
+     * @return   gets the value within the any.
      */
     public Object getObject() {
         return _object;

ridljar/com/sun/star/uno/Enum.java

@@ -2,9 +2,9 @@
  *
  *  $RCSfile: Enum.java,v $
  *
- *  $Revision: 1.1 $
+ *  $Revision: 1.2 $
  *
- *  last change: $Author: jsc $ $Date: 2000-11-08 15:39:30 $
+ *  last change: $Author: jbu $ $Date: 2002-01-18 14:04:55 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -66,11 +66,10 @@ package com.sun.star.uno;
  * as java binding for the IDL type enum.
  * Each java mapped enum class provides static member of this class
  * which represents the enum values.
- * You cant create a object of this class or subclass direct, to
+ * You cannot create a object of this class or subclass direct, to
  * avoid enum values with integer values outside the defined range.
  * <p>
- * @version     $Revision: 1.1 $ $ $Date: 2000-11-08 15:39:30 $
+ * @version     $Revision: 1.2 $ $ $Date: 2002-01-18 14:04:55 $
- * @author      Markus Meyer
  * @since       UDK1.0
  */
 public abstract class Enum {
@@ -86,7 +85,7 @@ public abstract class Enum {
     }
 
     /**
-     * Get the integer value of an enum value.<BR>
+     * Get the integer value of an enum value.
      * <p>
      * @return   the integer value.
      */

ridljar/com/sun/star/uno/IFieldDescription.java

@@ -2,9 +2,9 @@
  *
  *  $RCSfile: IFieldDescription.java,v $
  *
- *  $Revision: 1.1 $
+ *  $Revision: 1.2 $
  *
- *  last change: $Author: kr $ $Date: 2001-05-08 09:34:18 $
+ *  last change: $Author: jbu $ $Date: 2002-01-18 14:04:55 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -68,8 +68,7 @@ import java.lang.reflect.Field;
  * The <code>IFieldDescription</code> describes non
  * method members.
  * <p>
- * @version     $Revision: 1.1 $ $ $Date: 2001-05-08 09:34:18 $
+ * @version     $Revision: 1.2 $ $ $Date: 2002-01-18 14:04:55 $
- * @author      Kay Ramme
  * @since       UDK3.0
  */
 public interface IFieldDescription extends IMemberDescription {

ridljar/com/sun/star/uno/IMemberDescription.java

@@ -2,9 +2,9 @@
  *
  *  $RCSfile: IMemberDescription.java,v $
  *
- *  $Revision: 1.2 $
+ *  $Revision: 1.3 $
  *
- *  last change: $Author: jbu $ $Date: 2001-10-26 11:43:05 $
+ *  last change: $Author: jbu $ $Date: 2002-01-18 14:04:55 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -63,10 +63,10 @@ package com.sun.star.uno;
 
 /**
  * The <code>IMemberDescription</code> is the base interface
- * for members of UNO types <code>ITypeDescriptions</code>.
+ * for for the special subset of typedescriptions, which describe
+ * members of IDL structs or interfeces.
  * <p>
- * @version     $Revision: 1.2 $ $ $Date: 2001-10-26 11:43:05 $
+ * @version     $Revision: 1.3 $ $ $Date: 2002-01-18 14:04:55 $
- * @author      Kay Ramme
  * @since       UDK3.0
  */
 public interface IMemberDescription {
@@ -78,7 +78,7 @@ public interface IMemberDescription {
     String getName();
 
     /**
-     * Indicates if this member is unsigned.
+     * Indicates if this member is unsigned. (Not useful for IMethodDescription).
      * <p>
      * @return  the unsigned state
      */
@@ -100,9 +100,9 @@ public interface IMemberDescription {
 
     /**
      * Gives the relative index of this member in the declaring
-     * interface.
+     * interface or struct (including superclasses).
      * <p>
-     * @return  the realtive index of this member
+     * @return  the relative index of this member
      */
     int getIndex();
 }

ridljar/com/sun/star/uno/Type.java

@@ -2,9 +2,9 @@
  *
  *  $RCSfile: Type.java,v $
  *
- *  $Revision: 1.5 $
+ *  $Revision: 1.6 $
  *
- *  last change: $Author: kr $ $Date: 2001-05-08 09:34:18 $
+ *  last change: $Author: jbu $ $Date: 2002-01-18 14:04:55 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -73,9 +73,7 @@ import java.util.Hashtable;
  * to the java runtime system, e.g. for delaying the need of a class,
  * so that it is possible to generate it on the fly.
  * <p>
- * @version     $Revision: 1.5 $ $ $Date: 2001-05-08 09:34:18 $
+ * @version     $Revision: 1.6 $ $ $Date: 2002-01-18 14:04:55 $
- * @author      Markus Meyer
- * @author      Kay Ramme
  * @since       UDK1.0
  */
 public class Type {
@@ -162,7 +160,7 @@ public class Type {
      * the given <code>class</code>.
      * <p>
      * @since       UDK3.0
-     * @param zClass   the class of this type
+     * @param zClass   the java class of this type
      */
     public Type(Class zClass) {
         _class = zClass;
@@ -217,7 +215,10 @@ public class Type {
      * the given type name.
      * <p>
      * @since       UDK3.0
-     * @param typeName   the name of this type
+     * @param typeName   the name of this type. For simple types
+     *                   (numbers,string,type,any), the typeclass is calculated,
+     *                   for complex types (structs,interfaces), the
+     *                   typeclass of this object is set to UNKNOWN
      */
     public Type(String typeName) {
         _typeClass = (TypeClass)__typeNameToTypeClass.get(typeName);
@@ -234,7 +235,12 @@ public class Type {
      * the given <code>TypeClass</code>.
      * <p>
      * @since       UDK3.0
-     * @param typeClass   the <code>TypeClass</code> of this type
+     * @param typeClass   the <code>TypeClass</code> of this type. Only typeclass for
+     *                    simple types is allowed.
+     *
+     * @throws IllegalArgumentException when the typeClass is not simple (e.g.
+               a struct or an interface. The Constructor cannot find out the
+               name of the type in this case.
      */
     public Type(TypeClass typeClass) throws IllegalArgumentException {
         if(__isTypeClassPrimitive(typeClass)) {
@@ -278,12 +284,12 @@ public class Type {
     }
 
     /**
-     * Gets the class.
+     * Gets the java class.
      * Returns <code>null</code> if this
      * type has not been constructed by <code>Class</code>.
      * <p>
      * @since       UDK1.0
-     * @return  the type name.
+     * @return  the type name. Maybe null.
      */
     public Class getZClass() {
         return _class;
@@ -295,7 +301,7 @@ public class Type {
      * type has not been constructed by <code>TypeClass</code>.
      * <p>
      * @since       UDK1.0
-     * @return  the type name.
+     * @return  the type class. May be TypeClass.UNKNOWN.
      */
     public TypeClass getTypeClass() {
         return _typeClass;

ridljar/com/sun/star/uno/Union.java

@@ -2,9 +2,9 @@
  *
  *  $RCSfile: Union.java,v $
  *
- *  $Revision: 1.1 $
+ *  $Revision: 1.2 $
  *
- *  last change: $Author: jsc $ $Date: 2000-11-08 15:39:31 $
+ *  last change: $Author: jbu $ $Date: 2002-01-18 14:04:55 $
  *
  *  The Contents of this file are made available subject to the terms of
  *  either of the following licenses
@@ -65,8 +65,10 @@ package com.sun.star.uno;
  * The Union class is the base class for all classes generated
  * as java binding for the IDL type union.
  * <p>
- * @version     $Revision: 1.1 $ $ $Date: 2000-11-08 15:39:31 $
+ * Note: The idl type <code>union<code> is currently not fully
- * @author      Markus Meyer
+ * integrated into the UNO framework, so don't use it.
+ *
+ * @version     $Revision: 1.2 $ $ $Date: 2002-01-18 14:04:55 $
  * @since       UDK1.0
  */
 public class Union {