org.opends.messages
Class MessageBuilder

java.lang.Object
  extended by org.opends.messages.MessageBuilder
All Implemented Interfaces:
java.io.Serializable, java.lang.Appendable, java.lang.CharSequence

@PublicAPI(stability=UNCOMMITTED,
           mayInstantiate=true,
           mayExtend=false,
           mayInvoke=true)
public final class MessageBuilder
extends java.lang.Object
implements java.lang.Appendable, java.lang.CharSequence, java.io.Serializable

A builder used specifically for messages. As messages are appended they are translated to their string representation for storage using the locale specified in the constructor. Note that before you use this class you should consider whether it is appropriate. In general composing messages by appending message to each other may not produce a message that is formatted appropriately for all locales. It is usually better to create messages by composition. In other words you should create a base message that contains one or more string argument specifiers (%s) and define other message objects to use as replacement variables. In this way language translators have a change to reformat the message for a particular locale if necessary.

See Also:
Serialized Form

Constructor Summary
MessageBuilder()
          Constructs an instance that will build messages in the default locale.
MessageBuilder(java.util.Locale locale)
          Constructs an instance that will build messages in a specified locale.
MessageBuilder(Message message)
          Constructs an instance that will build messages in the default locale having an initial message.
MessageBuilder(MessageBuilder mb)
          Constructs an instance from another MessageBuilder.
MessageBuilder(java.lang.String message)
          Constructs an instance that will build messages in the default locale having an initial message.
 
Method Summary
 MessageBuilder append(char c)
          Appends the specified character to this Appendable.
 MessageBuilder append(java.lang.CharSequence cs)
          Append a string to this builder.
 MessageBuilder append(java.lang.CharSequence csq, int start, int end)
          Appends a subsequence of the specified character sequence to this Appendable.
 MessageBuilder append(int number)
          Append an integer to this builder.
 MessageBuilder append(Message message)
          Append a message to this builder.
 MessageBuilder append(java.lang.Object object)
          Append an object to this builder.
 char charAt(int index)
          Returns the char value at the specified index of the string representation of this builder using the default locale.
 char charAt(java.util.Locale locale, int index)
          Returns the char value at the specified index of the string representation of this builder using a specific locale.
 int length()
          Returns the length of the string representation of this builder using the default locale.
 int length(java.util.Locale locale)
          Returns the length of the string representation of this builder using a specific locale.
 java.lang.CharSequence subSequence(int start, int end)
          Returns a new CharSequence that is a subsequence of the string representation of this builder using the default locale.
 java.lang.CharSequence subSequence(java.util.Locale locale, int start, int end)
          Returns a new CharSequence that is a subsequence of the string representation of this builder using a specific locale.
 Message toMessage()
          Returns a raw message representation of the appended content.
 java.lang.String toString()
          Returns a string containing the characters in this sequence in the same order as this sequence.
 java.lang.String toString(java.util.Locale locale)
          Returns a string representation of the appended content in the specific locale.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

MessageBuilder

public MessageBuilder()
Constructs an instance that will build messages in the default locale.


MessageBuilder

public MessageBuilder(Message message)
Constructs an instance that will build messages in the default locale having an initial message.

Parameters:
message - initial message

MessageBuilder

public MessageBuilder(java.lang.String message)
Constructs an instance that will build messages in the default locale having an initial message.

Parameters:
message - initial message

MessageBuilder

public MessageBuilder(MessageBuilder mb)
Constructs an instance from another MessageBuilder.

Parameters:
mb - from which to construct a new message builder

MessageBuilder

public MessageBuilder(java.util.Locale locale)
Constructs an instance that will build messages in a specified locale.

Parameters:
locale - used for translating appended messages
Method Detail

append

public MessageBuilder append(Message message)
Append a message to this builder. The string representation of the locale specifed in the constructor will be stored in this builder.

Parameters:
message - to be appended
Returns:
reference to this builder

append

public MessageBuilder append(int number)
Append an integer to this builder.

Parameters:
number - to append
Returns:
reference to this builder

append

public MessageBuilder append(java.lang.Object object)
Append an object to this builder.

Parameters:
object - to append
Returns:
reference to this builder

append

public MessageBuilder append(java.lang.CharSequence cs)
Append a string to this builder.

Specified by:
append in interface java.lang.Appendable
Parameters:
cs - to append
Returns:
reference to this builder

append

public MessageBuilder append(java.lang.CharSequence csq,
                             int start,
                             int end)
                      throws java.lang.IndexOutOfBoundsException
Appends a subsequence of the specified character sequence to this Appendable.

An invocation of this method of the form out.append(csq, start, end) when csq is not null, behaves in exactly the same way as the invocation

     out.append(csq.subSequence(start, end)) 

Specified by:
append in interface java.lang.Appendable
Parameters:
csq - The character sequence from which a subsequence will be appended. If csq is null, then characters will be appended as if csq contained the four characters "null".
start - The index of the first character in the subsequence
end - The index of the character following the last character in the subsequence
Returns:
A reference to this Appendable
Throws:
java.lang.IndexOutOfBoundsException - If start or end are negative, start is greater than end, or end is greater than csq.length()

append

public MessageBuilder append(char c)
Appends the specified character to this Appendable.

Specified by:
append in interface java.lang.Appendable
Parameters:
c - The character to append
Returns:
A reference to this Appendable

toString

public java.lang.String toString()
Returns a string containing the characters in this sequence in the same order as this sequence. The length of the string will be the length of this sequence.

Specified by:
toString in interface java.lang.CharSequence
Overrides:
toString in class java.lang.Object
Returns:
a string consisting of exactly this sequence of characters

toString

public java.lang.String toString(java.util.Locale locale)
Returns a string representation of the appended content in the specific locale. Only Messages appended to this builder are rendered in the requested locale. Raw strings appended to this buffer are not translated to different locale.

Parameters:
locale - requested
Returns:
String representation

toMessage

public Message toMessage()
Returns a raw message representation of the appended content.

If the first object appended to this MessageBuilder was a Message then the returned message will inherit its category and severity. Otherwise the returned message will have category Category.USER_DEFINED and severity Severity.INFORMATION.

Returns:
Message raw message representing builder content

length

public int length()
Returns the length of the string representation of this builder using the default locale.

Specified by:
length in interface java.lang.CharSequence
Returns:
the number of chars in this message

charAt

public char charAt(int index)
            throws java.lang.IndexOutOfBoundsException
Returns the char value at the specified index of the string representation of this builder using the default locale.

Specified by:
charAt in interface java.lang.CharSequence
Parameters:
index - the index of the char value to be returned
Returns:
the specified char value
Throws:
java.lang.IndexOutOfBoundsException - if the index argument is negative or not less than length()

subSequence

public java.lang.CharSequence subSequence(int start,
                                          int end)
                                   throws java.lang.IndexOutOfBoundsException
Returns a new CharSequence that is a subsequence of the string representation of this builder using the default locale. The subsequence starts with the char value at the specified index and ends with the char value at index end - 1. The length (in chars) of the returned sequence is end - start, so if start == end then an empty sequence is returned.

Specified by:
subSequence in interface java.lang.CharSequence
Parameters:
start - the start index, inclusive
end - the end index, exclusive
Returns:
the specified subsequence
Throws:
java.lang.IndexOutOfBoundsException - if start or end are negative, if end is greater than length(), or if start is greater than end

length

public int length(java.util.Locale locale)
Returns the length of the string representation of this builder using a specific locale.

Parameters:
locale - for which the rendering of this message will be used in determining the length
Returns:
the number of chars in this message

charAt

public char charAt(java.util.Locale locale,
                   int index)
            throws java.lang.IndexOutOfBoundsException
Returns the char value at the specified index of the string representation of this builder using a specific locale.

Parameters:
locale - for which the rendering of this message will be used in determining the character
index - the index of the char value to be returned
Returns:
the specified char value
Throws:
java.lang.IndexOutOfBoundsException - if the index argument is negative or not less than length()

subSequence

public java.lang.CharSequence subSequence(java.util.Locale locale,
                                          int start,
                                          int end)
                                   throws java.lang.IndexOutOfBoundsException
Returns a new CharSequence that is a subsequence of the string representation of this builder using a specific locale. The subsequence starts with the char value at the specified index and ends with the char value at index end - 1. The length (in chars) of the returned sequence is end - start, so if start == end then an empty sequence is returned.

Parameters:
locale - for which the rendering of this message will be used in determining the character
start - the start index, inclusive
end - the end index, exclusive
Returns:
the specified subsequence
Throws:
java.lang.IndexOutOfBoundsException - if start or end are negative, if end is greater than length(), or if start is greater than end