Some of the more advanced features when working with documents and items.
If you have worked with Lotus Domino in the past then the document concept will be a very easy one for you to understand - they work in a very similar way. Remember this: a document contains items. Simple. Every time you use an action puakma gives you a HTMLDocument object to work with called ActionDocument. The ActionDocument is put together automatically for you based on the type of request being made (a GET or POST). You don't have to worry about parsing multipart/form-data submissions to extract the uploaded files - Puakma gives you an ActionDocument with the DocumentFileItem objects already attached.
Exception throwing is something we find a little verbose, so we take the C-programming approach and just return a null if your item or value does not exist. You must add the appropriate handler code to deal with these nulls (should they occur at run-time).
OK, so how do I access the items?
Just call the getItem("ItemName") method on the Document object, for example:
DocumentItem di = ActionDocument.getItem("ItemName");
if(di!=null)
{
//do something
}
The are a few types of item:
DocumentFileItem - for dealing with file attachments
DocumentMultiItem - for dealing with multivalued items (eg: the "SendTo" field when sending an email)
to access these items, call the same getItem() method, just cast it to the type you are dealing with:
DocumentMultiItem dmi = (DocumentMultiItem)ActionDocument.getItem("SendTo");
if(dmi!=null)
{
//do something
}
With me so far? Great. You can also test the type of item, just to be safe so you don't get any runtime casting errors. Following are the item types:
public static final int ITEM_TYPE_STRING = 1;
public static final int ITEM_TYPE_MULTI = 2;
public static final int ITEM_TYPE_FILE = 3;
public static final int ITEM_TYPE_BUFFER = 4;
public static final int ITEM_TYPE_RICH = 5; //for textarea, multi-lined stuff
public static final int ITEM_TYPE_DATE = 6;
public static final int ITEM_TYPE_NUMERIC = 7;
public static final int ITEM_TYPE_INTEGER = 8;
...and here's how you would use it:
if(di.getType()==DocumentItem.ITEM_TYPE_FILE)
{
DocumentFileItem dfi = (DocumentFileItem)di;
// process the file
}
Item types may be changed on the fly easily, by calling the setType(int) method, eg di.setType(DocumentItem.ITEM_TYPE_STRING); Note: Some item type convesions may fail! It is up to you to ensure the correctness of the conversion. Do not think you can simply change "abc" into a number by calling the setType() method....
Creating and Removing Items
You can create items in two ways:
1, From the Document, eg: ActionDocument.ReplaceItem("ItemName", "Value");
2. From the Item itself, eg: DocumentItem di = new DocumentItem(ActionDocument, "ItemName", "ItemValue");
Removing items is easy: ActionDocument.removeItem("ItemName"); or to get rid of them all, ActionDocument.removeAllItems();
Getting & setting item values
You can choose to deal with the item values from either the Document or from the DocumentItem. Using the Document saves a bit of code (as you don't have to first get the DocumentItem object), but is limited to a basic set of getXxxxxxValue() methods, one for each type of item (String, Date, Numeric, Object, ...).
String sName = ActionDocument.getItemValue("FullName");
...and conversely
ActionDocument.setItemValue("FullName", sName);
Internally within the DocumentItem object, all values (except files of course) are stored as a byte[] array. This is why if you call the getValue() method, a byte[] array is returned.
