Package com.groiss.wfxml

Class WfXMLForm

java.lang.Object
com.groiss.wfxml.WfXMLObject
com.groiss.wfxml.WfXMLForm
All Implemented Interfaces:
Cloneable
Direct Known Subclasses:
WfXMLDocForm, WfXMLFolder
public class WfXMLForm extends WfXMLObject implements 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 Details

  • Constructor Details

    • WfXMLForm

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

    • WfXMLForm

      public WfXMLForm(String id, int version, 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(org.apache.xmlbeans.XmlObject obj)

    • WfXMLForm

      public WfXMLForm(DMSForm dmsForm) throws 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:
      Exception - if the DMSForm is not filled and cannot be filled.

  • Method Details

    • setId

      public void setId(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 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 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(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(String name, long value)
      This method sets a field to a long 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(String name, int value)
      This method sets a field to an integer value. If you get the field value with the getField method, you will receive a Integer 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(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(String name, Object value)
      Use this method to set a field to various values. value can be one of the following:
      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 Object getField(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(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 List<WfXMLForm> getSubForms(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(String subject, String noteContent, 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 List<WfXMLNote> 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 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:
      Exception - if creating the DMSForm fails (e.g., no user found, etc.).

    • fill

      public void fill(DMSObject existingForm, User defaultCreator) throws 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:
      Exception - if no user could be found, or if something fails while objects are created and attached/added.

    • getName

      public 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.

    • getXMLObject

      public org.apache.xmlbeans.XmlObject getXMLObject()
      Specified by:
      getXMLObject in class WfXMLObject

    • clone

      public 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 Object