lekkimworld.com

To discuss and understand casting you must know that when you instantiate an object in Java you create an object on the heap and a reference to the object on the stack. In your Java agents you only have direct access to what’s on the stack which means that what you manipulate in your code are the references. Since you do not work with the objects on the heap directly the reference on the stack must tell the JVM which type of object is at the memory location pointed to on the heap.

Casting means taking an existing object reference and making it of another type. When most Java developers talk about casting they refer to “casting objects” which strictly speaking is wrong. It is however one of those things you learn to live with… 🙂

A simple example

As you might know every class in Java ultimatively inherits from java.lang.Object which means that a java.lang.Object reference can point to anything (much like a Variant in LotusScript). This means that you can always cast an object to java.lang.Object since it is a more generic type.

However you cannot store a java.lang.Object reference in a java.lang.String reference without casting since String is more specific than Object. As you can see I have to cast the obj reference to a String reference in line 3. If I don’t the code wont compile.

String sample1 = "This is my string..."; // create a String
Object obj     = sample1;                // store String in java.Object reference
String sample2 = (String)obj;            // we must cast to store an Object in a String
                                         // reference

To sum up you need to cast when refering to an object with a more specific reference than the current reference.

When casting references you may encounter the java.lang.ClassCastException which is an unchecked exception. This exception is the way the JVM can signal that you are doing an illegal cast for example casting a lotus.domino.Document to a lotus.domino.Database.

Knowing when it’s okay to cast

So how do you check if a cast is legal? Well apart from knowing which references you are dealing with you can use the instanceof keyword. The below example checks that the object really does inherit from lotus.domino.RichTextItem before casting:

// declarations
RichTextItem rt = null;
Item item = null;

// get document
Document doc = db.getDocumentByUnid("<some unid>");

// loop all items and put them into an ArrayList
Vector items = doc.getItems();
for (int i=0; i<items.size(); i++) {
   // get next element from the Vector (returns java.lang.Object)
   Object obj = items.elementAt(i);

   // is the item a RichTextItem?
   if (obj instanceof RichTextItem) {
      // yes it is - cast it as such
      rt = (RichTextItem)obj;
   } else {
      // nope - cast it as an Item
      item = (Item)obj;
   }
}

The above example is equivalent to the below code exept that I use the ClassCastException to find out that the cast is invalid.

// declarations
RichTextItem rt = null;
Item item = null;

// get document
Document doc = db.getDocumentByUnid("<some unid>");

// loop all items and put them into an ArrayList
Vector items = doc.getItems();
for (int i=0; i<items.size(); i++) {
   // get next element from the Vector (returns java.lang.Object)
   Object obj = items.elementAt(i);

   try {
      // try to cast as RichTextItem
      rt = (RichTextItem)obj;

      // coming here means that the item is a RichTextItem
      ...
   } catch (ClassCastException e) {
      // not a RichTextItem - cast it as an Item
      item = (Item)obj);
   }
}

Normal, or concrete, classes in Java can be instantiated using the new keyword. Concrete classes both define the functionality, that is what the class does, and the interface, that is what methods are available for you to call. Most of the classes you write will be concrete classes like the one below.

public class MyConcreteClass {
   public void perform() {
      ...
   }
}

At the other end of the spectrum we have an interface which only defines which methods we can call on it – there is no functionality in there. The interface in the example below specifies that a class implementing the interface will at least have the 4 listed methods. Notice that there is no method bodies (the compiler will enforce this).

public interface Car {
   public void increaseSpeed();
   public void decreaseSpeed();
   public void turnRight();
   public void turnLeft();
}

By creating a class and inserting the keyword “abstract” after the class visibility modifier (public, private, “friendly”) makes the class into an abstract class. An abstract class is somewhere in between an interface and a class, that is a class where some of the functionality is specified but not all. Think of an abstract class as a class with some blanks that needs to be filled in by any, non-abstract, class that extends it. An abstract class cannot be instantiated using the new keyword.

public abstract class MyAbstractClass {
   public class perform() {
      this.doStuff();
   }
   public abstract void doStuff();
}

How do I use an interface?

To use an interface you have your class implement it. Implementing an interface means making sure that the class specifies method bodies for all the methods in the interface. If you do not implement all the methods in the interface the compiler will make you mark the class as abstract.

public class Ford implements Car {
   public void increaseSpeed() {
      ...
   }
   public void decreaseSpeed() {
      ...
   }
   public void turnRight() {
      ...
   }
   public void turnLeft() {
      ...
   }
}

How do I use an abstract class?

An abstact class cannot be instantiated because some of the functionality (for example the doStuff() method in the example above) isn’t implemented. To use the class we need to extend it and implement any missing, abstract, methods.

public class MyClass extends MyAbstractClass {
   public void doStuff() {
      ...
   }
}

So when should I use which?

Well the real answer is it depends…

An abstract class is a good choice when you do most of the programming in the abstract class and leave only one or a couple of methods to sub-classes. An example could be a class that reads data from a file. The abstract class defines the actual reading and processing of the file and concrete sub-classes define how to get the file (from the local disk, via HTTP, via FTP etc.):

public abstract class FileProcessor {
   // declarations
   private File file = null;

   public process() {
      // get file
      this.file = this.getFile();

      // open file
      this.openFile();

      // decrypt file
      this.decryptFile();

      // do other stuff with the file
      ...
      ...
   }
   private void openFile() {
      ...
   }
   private void decryptFile() {
      ...
   }
   private abstract File getFile() throws Exception;
}

public class HttpFileProcessor extends FileProcessor {
   private abstract File getFile() throws Exception {
      // get file via HTTP and return it
      ...
   }
}

public class FtpFileProcessor extends FileProcessor {
   private abstract File getFile() throws Exception {
      // get file via FTP and return it
      ...
   }
}

An interface is really nice when all you need to do it define what methods are available but you want to leave the entire implementation up to the implementer. The interface in the example below only describes that a class implementing the interface knows how to process a Document object. You don’t care how the class does it but you know that you can call the process() method supplying the Document that should be processed.

public interface DocumentProcessor {
   public void process(Document doc) throws Exception;
}

Another really neat thing about interfaces is that a class may implement multiple interfaces whereas it can only extend a single class. This means you can use an interface simply to signal something (for an example of this look at the java.lang.Cloneable interface in the JDK).

public class MyCar implements Car, Cloneable, Serializable {
   ...
}

The Java Collection API was introduced in Java 1.2 and is a really nice API for handling dynamic arrays, sets, lists etc. The classes for the Collection API can be found in the java.util package. There is no built-in equivalent to the Collection API in LotusScript.

When coming from to Java from LotusScript the Collection API may be a little overwhelming to get cracking on. To kind of ease into it lets look at how to use the basic parts of the API for do kind of the same stuff in Java as you do in LotusScript.

Note: All the collection classes of the Collection API return references of type java.lang.Object which means that references oftentimes needs to be cast back to the desired type.

Dynamic arrays

In LotusScript you can use the Redim and Redim Preserve keywords to change the dimensions of an array at runtime. This isn’t possible in Java. Instead you can use an ArrayList which is an array-like structure that automatically resizes. If you are coming from Java in Notes/Domino 5.x the ArrayList is like a Vector only a little faster.

LotusScript
Dim my_array() As String
Dim i as Integer
For i=0 To 10
   Redim Preserve my_array(i)
   my_array(i) = "Index: " & i
Next

Java
import java.util.*;

ArrayList l = new ArrayList();
for (int i=0; i<11; i++) {
   l.add("Index: " + i);
}

As you can see there is no need to resize the ArrayList in the for-loop.

Lists

LotusScript has the concept of a List which is a key/value datastructure. In Java this kind of collection is called a Map and the most used type is the HashMap. For people coming from Java in Notes/Domino 5.x a HashMap is basically the same as a Hashtable only a wee bit faster.

LotusScript
Dim my_list List As String
my_list("one") = "1"
my_list("two") = "2"

Java
import java.util.*;

HashMap my_map = new HashMap();
my_map.put("one", "1");
my_map.put("two", "2");

Looping an array

All classes of the Collection API implementing the List/Set interface has an iterator() method that returns an Iterator object you can use to loop the collection.

LotusScript
Dim some_array(10) As String
Dim i As Integer
For i=0 To UBound(some_array)
   Print some_array(i)
Next

Java
import java.util.*;

ArrayList l = new ArrayList();
Iterator ite = l.iterator();
while (ite.hasNext()) {
   System.out.println(ite.next());
}
...or the slightly more condensed version I prefer...
ArrayList l = new ArrayList();
for (Iterator ite = l.iterator(); ite.hasNext(); ) {
   System.out.println(ite.next());
}

Looping a List

All classes of the Collection API implementing the Map interface has an keySet() method that returns a Set containing the keys used in the Map. From that Set you use the iterator() method to obtain an Iterator for looping.

LotusScript
Dim my_list List As String
my_list("one") = "1"
my_list("two") = "2"
Forall v In my_list
   Print Listtag(v) + " = " + v
End Forall

Java
import java.util.*;

HashMap my_map = new HashMap();
for (Iterator ite=my_map.keySet().iterator(); ite.hasNext(); ) {
   Object key = ite.next();
   System.out.println(key + " = " + my_map.get(key));
}

As you can see in the Java example the caveat here is to use the my_map.keySet() method to get a Set containing the keys in the Map. From the Set we can get an Iterator that we use to loop the keys of the Map.

Probably the biggest source of fustration for LotusScript programmers moving to Java is the fact that arrays cannot be resized in Java once they have been declared. Where in LotusScript we have the Redim keyword there is no equivalent for Java when talking arrays. If you need resizable arrays you should look into the Java Collection API (see the upcoming post “Java Collection API for LotusScript programmers” for more information on the Collection API).

Note: All references to arrays in Java are objects – also references to arrays of the privitive data types (int, long, char etc.).

As mentioned arrays dimensions are fixed in Java once declared and arrays always start at index 0. Notice how the bound has to be one higher than the number of places you need in the array. To declare a simple array with room for 5 Strings you write:

String[] my_strings = new String[5];
my_strings[0] = "abc";
my_strings[1] = "def";
my_strings[2] = "ghi";
my_strings[3] = "jkl";
my_strings[4] = "mno";

Alternatively you may also separate the declaration of the reference from the actual memory allocation.

String[] my_other_strings = null;
my_other_strings = new String[2];
my_other_strings[0] = "abc";
my_other_strings[1] = "def";

A cool thing with Java arrays is that you can use a more condensed syntax and fill the array as you declare it. It is a great way to avoid manually having to specify the dimensions of the array. The below code produces the same array as above (notice the use of curly braces).

String[] my_strings = {"abc", "def", "ghi", "jkl", "mno"};

This doesn’t just work for Strings but can be equally applied to other types of objects:

Object[] my_objects = {"abc", new java.util.Date(), new java.lang.Object()};

The reference to an array is kind of special in Java since it has a special member variable called length to help in looping the array. The basic construct for looping an array in Java is a for-loop just like in LotusScript. In the Java versions employed by Notes/Domino 7 and below there is no forall type loop.

String[] my_strings = {"abc", "def", "ghi", "jkl", "mno"};
for (int i=0; i<my_strings.length; i++) {
   System.out.println("Index " + i + ": " + my_strings[i]);
}

When working with arrays you really should be using the length member variable when looping arrays. If not you’ll most likely at some point run into the java.lang.ArrayIndexOutOfBoundsException which is an unchecked exception.