Modifies the instructions element to allow multiple instructions (JEP updated)

git-svn-id: http://svn.igniterealtime.org/svn/repos/smack/trunk@2299 b35dd754-fafc-0310-a699-88a17e54d16e

source/org/jivesoftware/smackx/Form.java

@@ -225,7 +225,16 @@ public class Form {
      * @return instructions that explain how to fill out the form.
      */
     public String getInstructions() {
-        return dataForm.getInstructions();
+        StringBuffer sb = new StringBuffer();
+        // Join the list of instructions together separated by newlines
+        for (Iterator it = dataForm.getInstructions(); it.hasNext();) {
+            sb.append((String) it.next());
+            // If this is not the last instruction then append a newline
+            if (it.hasNext()) {
+                sb.append("\n");
+            }
+        }
+        return sb.toString();
     }
 
 
@@ -266,7 +275,15 @@ public class Form {
      * @param instructions instructions that explain how to fill out the form.
      */
     public void setInstructions(String instructions) {
-        dataForm.setInstructions(instructions);
+        // Split the instructions into multiple instructions for each existent newline
+        ArrayList instructionsList = new ArrayList();
+        StringTokenizer st = new StringTokenizer(instructions, "\n");
+        while (st.hasMoreTokens()) {
+            instructionsList.add(st.nextToken());
+        }
+        // Set the new list of instructions
+        dataForm.setInstructions(instructionsList);
+        
     }
 
 
@@ -282,18 +299,15 @@ public class Form {
     
     /**
      * Returns a DataForm that serves to send this Form to the server. If the form is of type 
-     * submit, it may contain fields with no value. These fields will be remove since they only 
+     * submit, it may contain fields with no value. These fields will be removed since they only 
      * exist to assist the user while editing/completing the form in a UI. 
      * 
      * @return the wrapped DataForm.
      */
-    DataForm getDataFormToSend() {
+    public DataForm getDataFormToSend() {
         if (isSubmitType()) {
-            // Answer a new form based on the values of this form
+            // Create a new DataForm that contains only the answered fields 
             DataForm dataFormToSend = new DataForm(getType());
-            dataFormToSend.setInstructions(getInstructions());
-            dataFormToSend.setTitle(getTitle());
-            // Remove all the fields that have no answer
             for(Iterator it=getFields();it.hasNext();) {
                 FormField field = (FormField)it.next();
                 if (field.getValues().hasNext()) {

source/org/jivesoftware/smackx/packet/DataForm.java

@@ -69,7 +69,7 @@ public class DataForm implements PacketExtension {
 
     private String type;
     private String title;
-    private String instructions;
+    private List instructions = new ArrayList();
     private ReportedData reportedData;
     private List items = new ArrayList();
     private List fields = new ArrayList();
@@ -109,12 +109,17 @@ public class DataForm implements PacketExtension {
     }
 
     /**
-     * Returns the instructions that explain how to fill out the form and what the form is about.
+     * Returns an Iterator for the list of instructions that explain how to fill out the form and 
+     * what the form is about. The dataform could include multiple instructions since each 
+     * instruction could not contain newlines characters. Join the instructions together in order 
+     * to show them to the user.    
      * 
-     * @return instructions that explain how to fill out the form.
+     * @return an Iterator for the list of instructions that explain how to fill out the form.
      */
-    public String getInstructions() {
+    public Iterator getInstructions() {
-        return instructions;
+        synchronized (instructions) {
+            return Collections.unmodifiableList(new ArrayList(instructions)).iterator();
+        }
     }
 
     /**
@@ -167,11 +172,13 @@ public class DataForm implements PacketExtension {
     }
 
     /**
-     * Sets instructions that explain how to fill out the form and what the form is about.
+     * Sets the list of instructions that explain how to fill out the form and what the form is 
+     * about. The dataform could include multiple instructions since each instruction could not 
+     * contain newlines characters. 
      * 
-     * @param instructions instructions that explain how to fill out the form.
+     * @param instructions list of instructions that explain how to fill out the form.
      */
-    public void setInstructions(String instructions) {
+    public void setInstructions(List instructions) {
         this.instructions = instructions;
     }
 
@@ -195,6 +202,19 @@ public class DataForm implements PacketExtension {
         }
     }
     
+    /**
+     * Adds a new instruction to the list of instructions that explain how to fill out the form 
+     * and what the form is about. The dataform could include multiple instructions since each 
+     * instruction could not contain newlines characters. 
+     * 
+     * @param instruction the new instruction that explain how to fill out the form.
+     */
+    public void addInstruction(String instruction) {
+        synchronized (instructions) {
+            instructions.add(instruction);
+        }
+    }
+
     /**
      * Adds a new item returned from a search.
      * 
@@ -213,8 +233,8 @@ public class DataForm implements PacketExtension {
         if (getTitle() != null) {
             buf.append("<title>").append(getTitle()).append("</title>");
         }
-        if (getInstructions() != null) {
+        for (Iterator it=getInstructions(); it.hasNext();) {
-            buf.append("<instructions>").append(getInstructions()).append("</instructions>");
+            buf.append("<instructions>").append(it.next()).append("</instructions>");
         }
         // Append the list of fields returned from a search
         if (getReportedData() != null) {

source/org/jivesoftware/smackx/provider/DataFormProvider.java

@@ -83,7 +83,7 @@ public class DataFormProvider implements PacketExtensionProvider {
             int eventType = parser.next();
             if (eventType == XmlPullParser.START_TAG) {
                 if (parser.getName().equals("instructions")) { 
-                    dataForm.setInstructions(parser.nextText());
+                    dataForm.addInstruction(parser.nextText());
                 }
                 else if (parser.getName().equals("title")) {                    
                     dataForm.setTitle(parser.nextText());