com.groiss.wfxml
Class WfXMLForm

java.lang.Object
  com.groiss.wfxml.WfXMLObject
      com.groiss.wfxml.WfXMLForm

All Implemented Interfaces:

java.lang.Cloneable

Direct Known Subclasses:

WfXMLDocForm, WfXMLFolder

public class WfXMLForm
extends WfXMLObject
implements java.lang.Cloneable

This class can be used to represent forms. You can create new empty forms and add content to them. You can also create a WfXMLForm out of an existing DMSForm.
When you have created a WfXMLForm according to your needs, you can use it for sending within WfXML messages, and for creating DMSForms out of it.
See the super class WfXMLObject for a general explanation and examples.

Field Summary

protected java.util.Hashtable	content
protected static java.lang.String	FIELDDT
protected static java.lang.String	FORM_FIELD
protected static java.lang.String	FORM_FIELDNAME
protected static java.lang.String	FORMID
protected java.lang.String	formName
protected static java.lang.String	FORMSUBID
protected static java.lang.String	FORMUSER
protected static java.lang.String	FORMVERSION
protected java.lang.String	id
protected int	subformId
protected java.util.Hashtable	subForms
protected int	version

Fields inherited from class com.groiss.wfxml.WfXMLObject

namespace, notes, userId

Constructor Summary

WfXMLForm()
Creates a completely empty WfXMLForm object.

WfXMLForm(DMSForm dmsForm)
This constructor creates a WfXMLForm out of a DMSForm.

WfXMLForm(java.lang.String formName, org.jdom.Element formElem)
Use this constructor to create a WfXMLForm object out of a JDOM Element.

WfXMLForm(java.lang.String id, int version, java.lang.String userId)
Creates an empty WfXMLForm object and sets a form name, a class name, and a creator user id for the form.

Method Summary

void	addSubForm(WfXMLForm form, int subFormId) Add a subform to this WfXMLForm.
void	attachNote(java.lang.String subject, java.lang.String noteContent, java.lang.String noteCreator, boolean isPrivate) Adds a note to this form.
void	attachNote(WfXMLNote note) Adds a note to this form.
java.lang.Object	clone() Use the clone method if you need a copy of this WfXMLForm.
DMSObject	createDMSObject(User defaultCreator) This method creates DMSObject objects out of this WfXMLForm.
void	fill(DMSObject existingForm, User defaultCreator) This method fills an existing DMSForm with the values of this WfXMLForm.
org.jdom.Element	getAsXML() Use this method to get the content of this form represented as XML (with JDOM elements).
java.lang.Object	getField(java.lang.String name) Use this method to retrieve the value of one of this form's fields.
java.lang.String	getFormName() Returns the form name, with which the form is defined in process definitions.
java.lang.String	getId() Returns the id that has been set for this form.
java.lang.String	getName() This method returns the form name.
java.util.List	getNotes() Returns a List with all attached notes.
int	getSubformId() Returns the subform id.
java.util.List	getSubForms(java.lang.String subId) Returns a List containing all subforms for the given id.
int	getVersion() Returns the version that has been set for this form.
void	removeField(java.lang.String name) This method removes a field from this form.
void	setField(java.lang.String name, double value) Set a field to a double value.
void	setField(java.lang.String name, long value) This method sets a field to an integer value.
void	setField(java.lang.String name, java.lang.Object value) Use this method to set a field to various values.
void	setFormName(java.lang.String formName) Set the form name, with which the form is defined in process definitions.
void	setId(java.lang.String id) Sets an id for this WfXMLForm.
void	setSubformId(int id) Set a subform id for this form.
void	setVersion(int version) Use this method to set a version for the form.

Methods inherited from class com.groiss.wfxml.WfXMLObject

createInstance, createInstance, getUser, getUser, getUserId, setUserId

Methods inherited from class java.lang.Object

equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

FORMID

protected static final java.lang.String FORMID

See Also:

Constant Field Values

FORMVERSION

protected static final java.lang.String FORMVERSION

See Also:

Constant Field Values

FORMSUBID

protected static final java.lang.String FORMSUBID

See Also:

Constant Field Values

FORMUSER

protected static final java.lang.String FORMUSER

See Also:

Constant Field Values

FIELDDT

protected static final java.lang.String FIELDDT

See Also:

Constant Field Values

FORM_FIELD

protected static final java.lang.String FORM_FIELD

See Also:

Constant Field Values

FORM_FIELDNAME

protected static final java.lang.String FORM_FIELDNAME

See Also:

Constant Field Values

formName

protected java.lang.String formName

id

protected java.lang.String id

version

protected int version

subformId

protected int subformId

content

protected java.util.Hashtable content

subForms

protected java.util.Hashtable subForms

Constructor Detail

WfXMLForm

public WfXMLForm()

Creates a completely empty WfXMLForm object. Use the setter and add methods to add content to the form.

WfXMLForm

public WfXMLForm(java.lang.String id,
                 int version,
                 java.lang.String userId)

Creates an empty WfXMLForm object and sets a form name, a class name, and a creator user id for the form. Use the setter and add methods to add content to the form.

Parameters:

id - id and version are used to identify a FormType when a DMSForm object is created with this form.

version - The version of the FormType (see id).

userId - With this parameter you can specify the id of a user, who will be used when a DMSForm is created out of this form. If you don't want to set a special user for creating the form, you can simply pass null (in that case, WfXMLForm will try to create the DMSForm with another user --- default document creator, process instance creator...). If no user can be found, creating the DMSForm will fail.

WfXMLForm

public WfXMLForm(java.lang.String formName,
                 org.jdom.Element formElem)
          throws java.lang.IllegalArgumentException

Use this constructor to create a WfXMLForm object out of a JDOM Element.

Parameters:

formName - A form name if this form is used as process form. The form name must be a form name defined in a process definition. If this is no process form, pass null.

formElem - JDOM Element where the whole form content is located.

Throws:

java.lang.IllegalArgumentException - if formElem is an unexpected element with no form data.

WfXMLForm

public WfXMLForm(DMSForm dmsForm)
          throws java.lang.Exception

This constructor creates a WfXMLForm out of a DMSForm. The WfXMLForm will contain all fields, referenced forms, subforms, and attached notes.

Parameters:

dmsForm - The DMSForm of which you want to create a WfXMLForm.

Throws:

ApplicationException - if the DMSForm is not filled and cannot be filled.

java.lang.Exception

Method Detail

setId

public void setId(java.lang.String id)

Sets an id for this WfXMLForm. Together, id and version are used to identify the FormType of which this WfXMLForm is.

Parameters:

id - The id you want to set for this form.

getId

public java.lang.String getId()

Returns the id that has been set for this form. Together, id and version specify the FormType of which this WfXMLForm is.

Returns:

The id of this form.

setVersion

public void setVersion(int version)

Use this method to set a version for the form. Version and id are used to identify a FormType, which will be used when a DMSForm is created.

Parameters:

version - The new version you want to set for this form. version should be a positive value.

getVersion

public int getVersion()

Returns the version that has been set for this form. Version and id are used to identify a FormType, which will be used when a DMSForm is created.

Returns:

The version which has been set for this form. A value of -1 indicates, that no version has been set.

setSubformId

public void setSubformId(int id)

Set a subform id for this form. This makes sense if you want to use this form as subform.

Parameters:

id - The subform id (should be a positive value).

getSubformId

public int getSubformId()

Returns the subform id.

Returns:

The subform id. A value of -1 means, that no subform id has been set.

getFormName

public java.lang.String getFormName()

Returns the form name, with which the form is defined in process definitions.

Returns:

A string containing the form name or null if no form name has been specified.

setFormName

public void setFormName(java.lang.String formName)

Set the form name, with which the form is defined in process definitions.

Parameters:

formName - A string containing the form name

setField

public void setField(java.lang.String name,
                     long value)

This method sets a field to an integer value. If you get the field value with the getField method, you will receive a Long object.

Parameters:

name - Name of the field. If a field with this name already exists, the old value will be overwritten.

value - An integer value for that field.

setField

public void setField(java.lang.String name,
                     double value)

Set a field to a double value. If you get the value later with getField(java.lang.String) you will receive a Double object.

Parameters:

name - Name of the parameter you want to set.

value - A decimal value.

setField

public void setField(java.lang.String name,
                     java.lang.Object value)

Use this method to set a field to various values. value can be one of the following:

• String, a simple text value.
• Long, an integer value (you can use setField(String, long) to set a long value without creating an object.).
• Double, a decimal value (see also setField(String, double)).
• Date, a date (and time) value.
• User, a user.
• Role, a role.
• OrgUnit, a organizational unit.
• WfXMLForm, a reference to another form.

Parameters:

name - The name of the field. If a field with this name already exists, the old field value will be lost.

value - An Object holding the value that you want to set.

getField

public java.lang.Object getField(java.lang.String name)

Use this method to retrieve the value of one of this form's fields. The method returns an object of type Object because it is not sure what lies behind the field. Object can be one of the following:

• String, a simple text value.
• Long, an integer number.
• Double, a decimal value.
• Date, a date (and time) value.
• User, a user.
• Role, a role.
• OrgUnit, a organizational unit.
• WfXMLForm, if the field references another form.

Parameters:

name - The name of the field that you want to retrieve.

Returns:

An object representing the value of the field, or null if no value is set for a field with the name name.

removeField

public void removeField(java.lang.String name)

This method removes a field from this form. If the field does not exist, nothing happens.

Parameters:

name - The name of the field you want to remove.

addSubForm

public void addSubForm(WfXMLForm form,
                       int subFormId)

Add a subform to this WfXMLForm. You must specify an id for adding the subform. The type of the added form is set to TYPE_SUB automatically.

Parameters:

form - A WfXMLForm you want to add as subform.

subFormId - The id for which the subform will be added.

getSubForms

public java.util.List getSubForms(java.lang.String subId)

Returns a List containing all subforms for the given id. The list contains WfXMLForm objects.

Parameters:

subId - The id for which you want to receive subforms.

Returns:

A List with all subforms (WfXMLForm objects). Use the returned list in a read-only way!

attachNote

public void attachNote(java.lang.String subject,
                       java.lang.String noteContent,
                       java.lang.String noteCreator,
                       boolean isPrivate)

Adds a note to this form. The note will be attached to the form, when DMSObject objects are created with the createDMSObject method.

Parameters:

subject - A subject for the note.

noteContent - The content of the note.

noteCreator - The user id of the user who is the creator of the note. If you don't want to set a special user here, use null. In that case another user will be used for creating the note (line in the createDMSObject method.

isPrivate - true makes the note private, thus being viewable only for its creator. false means that the note is public and can be viewed by anybody.

attachNote

public void attachNote(WfXMLNote note)

Adds a note to this form. The note will be attached to the form, when DMSObject objects are created with the createDMSObject method.

Parameters:

note - A WfXMLNote object representing the note that you want to add.

getNotes

public java.util.List getNotes()

Returns a List with all attached notes. The List is filled with WfXMLNote objects.

Returns:

A list containing all attached notes as WfXMLNote objects. Use the returned list in a read-only way!

createDMSObject

public DMSObject createDMSObject(User defaultCreator)
                          throws java.lang.Exception

This method creates DMSObject objects out of this WfXMLForm. At least a DMSForm object will be created. That object represents this form. Additionally other objects may be created (e.g., subforms, notes, ...).
All these objects will be created with the users who have been set for them. If no user has been set, the method will use the defaultCreator to create objects. If no user can be found at all, an exception is thrown.

Specified by:

createDMSObject in class WfXMLObject

Parameters:

defaultCreator - DMSObjects will be created with this user, if no particular user is defined for them. If you don't want to set a default creator, simply pass null.

Returns:

A reference to the DMSForm, which represents this WfXMLForm.

Throws:

ApplicationException - if creating the DMSForm fails (e.g., no user found, etc.).

java.lang.Exception

fill

public void fill(DMSObject existingForm,
                 User defaultCreator)
          throws java.lang.Exception

This method fills an existing DMSForm with the values of this WfXMLForm. It's similar to createDMSObject(com.groiss.org.User), with the only difference, that the DMSForm must already exist.
Notes and subforms will also be created and attached to the DMSForm. All values that have been defined in this WfXMLForm will be set in the DMSForm. So values, which exist in the DMSForm, will not be changed, if they are not defined in the WfXMLForm...
After filling the form with data, changes are stored in the database.

Specified by:

fill in class WfXMLObject

Parameters:

existingForm - An existing DMSForm, which will be filled with the values set in this WfXMLForm. If you pass an object of a different type to this method, nothing will be done.

defaultCreator - A default user for creating objects (notes, subforms), if no particular user is defined for creating them. You can set this parameter to null if you don't want to provide a default creator.

Throws:

ApplicationException - if no user could be found, or if something fails while objects are created and attached/added.

java.lang.Exception - if updating the object fails.

getName

public java.lang.String getName()

This method returns the form name. The form name is the name of the form, as it is displayed in a DMS folder when a form is located there. The form name is one or more of the form fields (the form type defines which form fields have to be used to build the form name). For getting the form name the corresponding FormType must be present (id and version). If no such form type exists on the local server, null will be returned.

Specified by:

getName in class WfXMLObject

Returns:

Returns the name of the form, or null if the name cannot be read. That might happen if the specified form type is not available, or if the form does not contain any of the fields which form the name.

getAsXML

public org.jdom.Element getAsXML()

Use this method to get the content of this form represented as XML (with JDOM elements). The returned element contains all fields, values, referenced forms and subforms.

Specified by:

getAsXML in class WfXMLObject

Returns:

A JDOM Element containing the whole content of this form.

clone

public java.lang.Object clone()

Use the clone method if you need a copy of this WfXMLForm. This method creates a kind of deep copy of the WfXMLForm, but, in fact, the copy is not completely deep.
So, what will be copied is the following:

• id
• version
• formName
• userId
• type (main, reference, sub)
• fields plus simple String field values
• subform ids

But: All WfXMLForm objects that have been added to this WfXMLForm object (as subForms or fields) will not be cloned! For most cases this is a good behavior.
What you can do with the cloned form (without affecting the old form) includes:

• changing id, version, form name, type
• adding new fields
• removing fields
• adding new subforms
• attaching notes

The only thing you must take care with, is when you want to perform changes on other WfXMLForm objects or WfXMLNotes:

• when you retrieve a WfXMLForm with getField(String), you will retrieve a reference to the WfXMLForm object which is still referenced by the old form (of which the copy was made), too.
• when you get a List of subforms with the getSubForms method, changes to that list do not affect the old form (because that List has been copied, too), but: the WfXMLForm objects referenced by this List were not copied, so again you retrieve references to the same WfXMLForm objects that are also still referenced by the old form, when you access the List's content.
• getNotes gives you a list of all notes. This list is copied, so changes to the list don't affect the old WfXMLForm. If you access the content of the list and if you change the WfXMLNote objects, which are in the list, the WfXMLNote objects of the old WfXMLForm are also changed.

So, if there is really need of changing a subform or a referenced form, you should do the following:

1. get the form (e.g., getField)
2. remove the form (e.g., removeField)
3. clone the form
4. do changes on the form
5. and finally add the changed form again

If this is too complicated, you could consider building up a new WfXMLForm..., or you could do a

new WfXMLForm(null, yourOldForm.getAsXML())

This, in fact, creates a real deep copy with all subforms and referenced forms, because first XML code is genereted and then a new WfXMLForm is build with that XML code... (which is expensive, of course).

Overrides:

clone in class java.lang.Object