Message.java

  1. /**
  2.  *
  3.  * Copyright 2003-2007 Jive Software.
  4.  *
  5.  * Licensed under the Apache License, Version 2.0 (the "License");
  6.  * you may not use this file except in compliance with the License.
  7.  * You may obtain a copy of the License at
  8.  *
  9.  *     http://www.apache.org/licenses/LICENSE-2.0
  10.  *
  11.  * Unless required by applicable law or agreed to in writing, software
  12.  * distributed under the License is distributed on an "AS IS" BASIS,
  13.  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14.  * See the License for the specific language governing permissions and
  15.  * limitations under the License.
  16.  */

  18. package org.jivesoftware.smack.packet;

  20. import java.util.ArrayList;
  21. import java.util.Collections;
  22. import java.util.HashSet;
  23. import java.util.List;
  24. import java.util.Locale;
  25. import java.util.Set;

  27. import org.jivesoftware.smack.util.TypedCloneable;
  28. import org.jivesoftware.smack.util.XmlStringBuilder;
  29. import org.jxmpp.jid.Jid;

  31. /**
  32.  * Represents XMPP message packets. A message can be one of several types:
  33.  *
  34.  * <ul>
  35.  *      <li>Message.Type.NORMAL -- (Default) a normal text message used in email like interface.
  36.  *      <li>Message.Type.CHAT -- a typically short text message used in line-by-line chat interfaces.
  37.  *      <li>Message.Type.GROUP_CHAT -- a chat message sent to a groupchat server for group chats.
  38.  *      <li>Message.Type.HEADLINE -- a text message to be displayed in scrolling marquee displays.
  39.  *      <li>Message.Type.ERROR -- indicates a messaging error.
  40.  * </ul>
  41.  *
  42.  * For each message type, different message fields are typically used as follows:
  43.  * <p>
  44.  * <table border="1">
  45.  * <tr><td>&nbsp;</td><td colspan="5"><b>Message type</b></td></tr>
  46.  * <tr><td><i>Field</i></td><td><b>Normal</b></td><td><b>Chat</b></td><td><b>Group Chat</b></td><td><b>Headline</b></td><td><b>XMPPError</b></td></tr>
  47.  * <tr><td><i>subject</i></td> <td>SHOULD</td><td>SHOULD NOT</td><td>SHOULD NOT</td><td>SHOULD NOT</td><td>SHOULD NOT</td></tr>
  48.  * <tr><td><i>thread</i></td>  <td>OPTIONAL</td><td>SHOULD</td><td>OPTIONAL</td><td>OPTIONAL</td><td>SHOULD NOT</td></tr>
  49.  * <tr><td><i>body</i></td>    <td>SHOULD</td><td>SHOULD</td><td>SHOULD</td><td>SHOULD</td><td>SHOULD NOT</td></tr>
  50.  * <tr><td><i>error</i></td>   <td>MUST NOT</td><td>MUST NOT</td><td>MUST NOT</td><td>MUST NOT</td><td>MUST</td></tr>
  51.  * </table>
  52.  *
  53.  * @author Matt Tucker
  54.  */
  55. public final class Message extends Stanza implements TypedCloneable<Message> {

  57.     public static final String ELEMENT = "message";
  58.     public static final String BODY = "body";

  60.     private Type type;
  61.     private String thread = null;

  63.     private final Set<Subject> subjects = new HashSet<Subject>();
  64.     private final Set<Body> bodies = new HashSet<Body>();

  66.     /**
  67.      * Creates a new, "normal" message.
  68.      */
  69.     public Message() {
  70.     }

  72.     /**
  73.      * Creates a new "normal" message to the specified recipient.
  74.      *
  75.      * @param to the recipient of the message.
  76.      */
  77.     public Message(Jid to) {
  78.         setTo(to);
  79.     }

  81.     /**
  82.      * Creates a new message of the specified type to a recipient.
  83.      *
  84.      * @param to the user to send the message to.
  85.      * @param type the message type.
  86.      */
  87.     public Message(Jid to, Type type) {
  88.         this(to);
  89.         setType(type);
  90.     }

  92.     /**
  93.      * Creates a new message to the specified recipient and with the specified body.
  94.      *
  95.      * @param to the user to send the message to.
  96.      * @param body the body of the message.
  97.      */
  98.     public Message(Jid to, String body) {
  99.         this(to);
  100.         setBody(body);
  101.     }

  103.     /**
  104.      * Copy constructor.
  105.      * <p>
  106.      * This does not perform a deep clone, as extension elements are shared between the new and old
  107.      * instance.
  108.      * </p>
  109.      *
  110.      * @param other
  111.      */
  112.     public Message(Message other) {
  113.         super(other);
  114.         this.type = other.type;
  115.         this.thread = other.thread;
  116.         this.subjects.addAll(other.subjects);
  117.         this.bodies.addAll(other.bodies);
  118.     }

  120.     /**
  121.      * Returns the type of the message. If no type has been set this method will return {@link
  122.      * org.jivesoftware.smack.packet.Message.Type#normal}.
  123.      *
  124.      * @return the type of the message.
  125.      */
  126.     public Type getType() {
  127.         if (type == null) {
  128.             return Type.normal;
  129.         }
  130.         return type;
  131.     }

  133.     /**
  134.      * Sets the type of the message.
  135.      *
  136.      * @param type the type of the message.
  137.      */
  138.     public void setType(Type type) {
  139.         this.type = type;
  140.     }

  142.     /**
  143.      * Returns the default subject of the message, or null if the subject has not been set.
  144.      * The subject is a short description of message contents.
  145.      * <p>
  146.      * The default subject of a message is the subject that corresponds to the message's language.
  147.      * (see {@link #getLanguage()}) or if no language is set to the applications default
  148.      * language (see {@link Stanza#getDefaultLanguage()}).
  149.      *
  150.      * @return the subject of the message.
  151.      */
  152.     public String getSubject() {
  153.         return getSubject(null);
  154.     }
  155.     
  156.     /**
  157.      * Returns the subject corresponding to the language. If the language is null, the method result
  158.      * will be the same as {@link #getSubject()}. Null will be returned if the language does not have
  159.      * a corresponding subject.
  160.      *
  161.      * @param language the language of the subject to return.
  162.      * @return the subject related to the passed in language.
  163.      */
  164.     public String getSubject(String language) {
  165.         Subject subject = getMessageSubject(language);
  166.         return subject == null ? null : subject.subject;
  167.     }
  168.     
  169.     private Subject getMessageSubject(String language) {
  170.         language = determineLanguage(language);
  171.         for (Subject subject : subjects) {
  172.             if (language.equals(subject.language)) {
  173.                 return subject;
  174.             }
  175.         }
  176.         return null;
  177.     }

  179.     /**
  180.      * Returns a set of all subjects in this Message, including the default message subject accessible
  181.      * from {@link #getSubject()}.
  182.      *
  183.      * @return a collection of all subjects in this message.
  184.      */
  185.     public Set<Subject> getSubjects() {
  186.         return Collections.unmodifiableSet(subjects);
  187.     }

  189.     /**
  190.      * Sets the subject of the message. The subject is a short description of
  191.      * message contents.
  192.      *
  193.      * @param subject the subject of the message.
  194.      */
  195.     public void setSubject(String subject) {
  196.         if (subject == null) {
  197.             removeSubject(""); // use empty string because #removeSubject(null) is ambiguous 
  198.             return;
  199.         }
  200.         addSubject(null, subject);
  201.     }

  203.     /**
  204.      * Adds a subject with a corresponding language.
  205.      *
  206.      * @param language the language of the subject being added.
  207.      * @param subject the subject being added to the message.
  208.      * @return the new {@link org.jivesoftware.smack.packet.Message.Subject}
  209.      * @throws NullPointerException if the subject is null, a null pointer exception is thrown
  210.      */
  211.     public Subject addSubject(String language, String subject) {
  212.         language = determineLanguage(language);
  213.         Subject messageSubject = new Subject(language, subject);
  214.         subjects.add(messageSubject);
  215.         return messageSubject;
  216.     }

  218.     /**
  219.      * Removes the subject with the given language from the message.
  220.      *
  221.      * @param language the language of the subject which is to be removed
  222.      * @return true if a subject was removed and false if it was not.
  223.      */
  224.     public boolean removeSubject(String language) {
  225.         language = determineLanguage(language);
  226.         for (Subject subject : subjects) {
  227.             if (language.equals(subject.language)) {
  228.                 return subjects.remove(subject);
  229.             }
  230.         }
  231.         return false;
  232.     }

  234.     /**
  235.      * Removes the subject from the message and returns true if the subject was removed.
  236.      *
  237.      * @param subject the subject being removed from the message.
  238.      * @return true if the subject was successfully removed and false if it was not.
  239.      */
  240.     public boolean removeSubject(Subject subject) {
  241.         return subjects.remove(subject);
  242.     }

  244.     /**
  245.      * Returns all the languages being used for the subjects, not including the default subject.
  246.      *
  247.      * @return the languages being used for the subjects.
  248.      */
  249.     public List<String> getSubjectLanguages() {
  250.         Subject defaultSubject = getMessageSubject(null);
  251.         List<String> languages = new ArrayList<String>();
  252.         for (Subject subject : subjects) {
  253.             if (!subject.equals(defaultSubject)) {
  254.                 languages.add(subject.language);
  255.             }
  256.         }
  257.         return Collections.unmodifiableList(languages);
  258.     }

  260.     /**
  261.      * Returns the default body of the message, or null if the body has not been set. The body
  262.      * is the main message contents.
  263.      * <p>
  264.      * The default body of a message is the body that corresponds to the message's language.
  265.      * (see {@link #getLanguage()}) or if no language is set to the applications default
  266.      * language (see {@link Stanza#getDefaultLanguage()}).
  267.      *
  268.      * @return the body of the message.
  269.      */
  270.     public String getBody() {
  271.         return getBody(null);
  272.     }

  274.     /**
  275.      * Returns the body corresponding to the language. If the language is null, the method result
  276.      * will be the same as {@link #getBody()}. Null will be returned if the language does not have
  277.      * a corresponding body.
  278.      *
  279.      * @param language the language of the body to return.
  280.      * @return the body related to the passed in language.
  281.      * @since 3.0.2
  282.      */
  283.     public String getBody(String language) {
  284.         Body body = getMessageBody(language);
  285.         return body == null ? null : body.message;
  286.     }
  287.     
  288.     private Body getMessageBody(String language) {
  289.         language = determineLanguage(language);
  290.         for (Body body : bodies) {
  291.             if (language.equals(body.language)) {
  292.                 return body;
  293.             }
  294.         }
  295.         return null;
  296.     }

  298.     /**
  299.      * Returns a set of all bodies in this Message, including the default message body accessible
  300.      * from {@link #getBody()}.
  301.      *
  302.      * @return a collection of all bodies in this Message.
  303.      * @since 3.0.2
  304.      */
  305.     public Set<Body> getBodies() {
  306.         return Collections.unmodifiableSet(bodies);
  307.     }

  309.     /**
  310.      * Sets the body of the message. The body is the main message contents.
  311.      *
  312.      * @param body the body of the message.
  313.      */
  314.     public void setBody(String body) {
  315.         if (body == null) {
  316.             removeBody(""); // use empty string because #removeBody(null) is ambiguous
  317.             return;
  318.         }
  319.         addBody(null, body);
  320.     }

  322.     /**
  323.      * Adds a body with a corresponding language.
  324.      *
  325.      * @param language the language of the body being added.
  326.      * @param body the body being added to the message.
  327.      * @return the new {@link org.jivesoftware.smack.packet.Message.Body}
  328.      * @throws NullPointerException if the body is null, a null pointer exception is thrown
  329.      * @since 3.0.2
  330.      */
  331.     public Body addBody(String language, String body) {
  332.         language = determineLanguage(language);
  333.         Body messageBody = new Body(language, body);
  334.         bodies.add(messageBody);
  335.         return messageBody;
  336.     }

  338.     /**
  339.      * Removes the body with the given language from the message.
  340.      *
  341.      * @param language the language of the body which is to be removed
  342.      * @return true if a body was removed and false if it was not.
  343.      */
  344.     public boolean removeBody(String language) {
  345.         language = determineLanguage(language);
  346.         for (Body body : bodies) {
  347.             if (language.equals(body.language)) {
  348.                 return bodies.remove(body);
  349.             }
  350.         }
  351.         return false;
  352.     }

  354.     /**
  355.      * Removes the body from the message and returns true if the body was removed.
  356.      *
  357.      * @param body the body being removed from the message.
  358.      * @return true if the body was successfully removed and false if it was not.
  359.      * @since 3.0.2
  360.      */
  361.     public boolean removeBody(Body body) {
  362.         return bodies.remove(body);
  363.     }

  365.     /**
  366.      * Returns all the languages being used for the bodies, not including the default body.
  367.      *
  368.      * @return the languages being used for the bodies.
  369.      * @since 3.0.2
  370.      */
  371.     public List<String> getBodyLanguages() {
  372.         Body defaultBody = getMessageBody(null);
  373.         List<String> languages = new ArrayList<String>();
  374.         for (Body body : bodies) {
  375.             if (!body.equals(defaultBody)) {
  376.                 languages.add(body.language);
  377.             }
  378.         }
  379.         return Collections.unmodifiableList(languages);
  380.     }

  382.     /**
  383.      * Returns the thread id of the message, which is a unique identifier for a sequence
  384.      * of "chat" messages. If no thread id is set, <tt>null</tt> will be returned.
  385.      *
  386.      * @return the thread id of the message, or <tt>null</tt> if it doesn't exist.
  387.      */
  388.     public String getThread() {
  389.         return thread;
  390.     }

  392.     /**
  393.      * Sets the thread id of the message, which is a unique identifier for a sequence
  394.      * of "chat" messages.
  395.      *
  396.      * @param thread the thread id of the message.
  397.      */
  398.     public void setThread(String thread) {
  399.         this.thread = thread;
  400.     }

  402.     private String determineLanguage(String language) {
  403.         
  404.         // empty string is passed by #setSubject() and #setBody() and is the same as null
  405.         language = "".equals(language) ? null : language;

  407.         // if given language is null check if message language is set
  408.         if (language == null && this.language != null) {
  409.             return this.language;
  410.         }
  411.         else if (language == null) {
  412.             return getDefaultLanguage();
  413.         }
  414.         else {
  415.             return language;
  416.         }
  417.         
  418.     }

  420.     @Override
  421.     public XmlStringBuilder toXML() {
  422.         XmlStringBuilder buf = new XmlStringBuilder();
  423.         buf.halfOpenElement(ELEMENT);
  424.         addCommonAttributes(buf);
  425.         buf.optAttribute("type", type);
  426.         buf.rightAngleBracket();

  428.         // Add the subject in the default language
  429.         Subject defaultSubject = getMessageSubject(null);
  430.         if (defaultSubject != null) {
  431.             buf.element("subject", defaultSubject.subject);
  432.         }
  433.         // Add the subject in other languages
  434.         for (Subject subject : getSubjects()) {
  435.             // Skip the default language
  436.             if(subject.equals(defaultSubject))
  437.                 continue;
  438.             buf.halfOpenElement("subject").xmllangAttribute(subject.language).rightAngleBracket();
  439.             buf.escape(subject.subject);
  440.             buf.closeElement("subject");
  441.         }
  442.         // Add the body in the default language
  443.         Body defaultBody = getMessageBody(null);
  444.         if (defaultBody != null) {
  445.             buf.element("body", defaultBody.message);
  446.         }
  447.         // Add the bodies in other languages
  448.         for (Body body : getBodies()) {
  449.             // Skip the default language
  450.             if(body.equals(defaultBody))
  451.                 continue;
  452.             buf.halfOpenElement(BODY).xmllangAttribute(body.getLanguage()).rightAngleBracket();
  453.             buf.escape(body.getMessage());
  454.             buf.closeElement(BODY);
  455.         }
  456.         buf.optElement("thread", thread);
  457.         // Append the error subpacket if the message type is an error.
  458.         if (type == Type.error) {
  459.             appendErrorIfExists(buf);
  460.         }
  461.         // Add packet extensions, if any are defined.
  462.         buf.append(getExtensionsXML());
  463.         buf.closeElement(ELEMENT);
  464.         return buf;
  465.     }

  467.     /**
  468.      * Creates and returns a copy of this message stanza.
  469.      * <p>
  470.      * This does not perform a deep clone, as extension elements are shared between the new and old
  471.      * instance.
  472.      * </p>
  473.      * @return a clone of this message.
  474.      */
  475.     @Override
  476.     public Message clone() {
  477.         return new Message(this);
  478.     }

  480.     /**
  481.      * Represents a message subject, its language and the content of the subject.
  482.      */
  483.     public static class Subject {

  485.         private final String subject;
  486.         private final String language;

  488.         private Subject(String language, String subject) {
  489.             if (language == null) {
  490.                 throw new NullPointerException("Language cannot be null.");
  491.             }
  492.             if (subject == null) {
  493.                 throw new NullPointerException("Subject cannot be null.");
  494.             }
  495.             this.language = language;
  496.             this.subject = subject;
  497.         }

  499.         /**
  500.          * Returns the language of this message subject.
  501.          *
  502.          * @return the language of this message subject.
  503.          */
  504.         public String getLanguage() {
  505.             return language;
  506.         }

  508.         /**
  509.          * Returns the subject content.
  510.          *
  511.          * @return the content of the subject.
  512.          */
  513.         public String getSubject() {
  514.             return subject;
  515.         }


  518.         public int hashCode() {
  519.             final int prime = 31;
  520.             int result = 1;
  521.             result = prime * result + this.language.hashCode();
  522.             result = prime * result + this.subject.hashCode();
  523.             return result;
  524.         }

  526.         public boolean equals(Object obj) {
  527.             if (this == obj) {
  528.                 return true;
  529.             }
  530.             if (obj == null) {
  531.                 return false;
  532.             }
  533.             if (getClass() != obj.getClass()) {
  534.                 return false;
  535.             }
  536.             Subject other = (Subject) obj;
  537.             // simplified comparison because language and subject are always set
  538.             return this.language.equals(other.language) && this.subject.equals(other.subject);
  539.         }
  540.         
  541.     }

  543.     /**
  544.      * Represents a message body, its language and the content of the message.
  545.      */
  546.     public static class Body {

  548.         private final String message;
  549.         private final String language;

  551.         private Body(String language, String message) {
  552.             if (language == null) {
  553.                 throw new NullPointerException("Language cannot be null.");
  554.             }
  555.             if (message == null) {
  556.                 throw new NullPointerException("Message cannot be null.");
  557.             }
  558.             this.language = language;
  559.             this.message = message;
  560.         }

  562.         /**
  563.          * Returns the language of this message body.
  564.          *
  565.          * @return the language of this message body.
  566.          */
  567.         public String getLanguage() {
  568.             return language;
  569.         }

  571.         /**
  572.          * Returns the message content.
  573.          *
  574.          * @return the content of the message.
  575.          */
  576.         public String getMessage() {
  577.             return message;
  578.         }

  580.         public int hashCode() {
  581.             final int prime = 31;
  582.             int result = 1;
  583.             result = prime * result + this.language.hashCode();
  584.             result = prime * result + this.message.hashCode();
  585.             return result;
  586.         }

  588.         public boolean equals(Object obj) {
  589.             if (this == obj) {
  590.                 return true;
  591.             }
  592.             if (obj == null) {
  593.                 return false;
  594.             }
  595.             if (getClass() != obj.getClass()) {
  596.                 return false;
  597.             }
  598.             Body other = (Body) obj;
  599.             // simplified comparison because language and message are always set
  600.             return this.language.equals(other.language) && this.message.equals(other.message);
  601.         }
  602.         
  603.     }

  605.     /**
  606.      * Represents the type of a message.
  607.      */
  608.     public enum Type {

  610.         /**
  611.          * (Default) a normal text message used in email like interface.
  612.          */
  613.         normal,

  615.         /**
  616.          * Typically short text message used in line-by-line chat interfaces.
  617.          */
  618.         chat,

  620.         /**
  621.          * Chat message sent to a groupchat server for group chats.
  622.          */
  623.         groupchat,

  625.         /**
  626.          * Text message to be displayed in scrolling marquee displays.
  627.          */
  628.         headline,

  630.         /**
  631.          * indicates a messaging error.
  632.          */
  633.         error;

  635.         /**
  636.          * Converts a String into the corresponding types. Valid String values that can be converted
  637.          * to types are: "normal", "chat", "groupchat", "headline" and "error".
  638.          * 
  639.          * @param string the String value to covert.
  640.          * @return the corresponding Type.
  641.          * @throws IllegalArgumentException when not able to parse the string parameter
  642.          * @throws NullPointerException if the string is null
  643.          */
  644.         public static Type fromString(String string) {
  645.             return Type.valueOf(string.toLowerCase(Locale.US));
  646.         }

  648.     }
  649. }
Created with JaCoCo 0.7.4.201502262128