/*
|
* CDDL HEADER START
|
*
|
* The contents of this file are subject to the terms of the
|
* Common Development and Distribution License, Version 1.0 only
|
* (the "License"). You may not use this file except in compliance
|
* with the License.
|
*
|
* You can obtain a copy of the license at
|
* trunk/opends/resource/legal-notices/OpenDS.LICENSE
|
* or https://OpenDS.dev.java.net/OpenDS.LICENSE.
|
* See the License for the specific language governing permissions
|
* and limitations under the License.
|
*
|
* When distributing Covered Code, include this CDDL HEADER in each
|
* file and include the License file at
|
* trunk/opends/resource/legal-notices/OpenDS.LICENSE. If applicable,
|
* add the following below this CDDL HEADER, with the fields enclosed
|
* by brackets "[]" replaced with your own identifying information:
|
* Portions Copyright [yyyy] [name of copyright owner]
|
*
|
* CDDL HEADER END
|
*
|
*
|
* Copyright 2007-2009 Sun Microsystems, Inc.
|
*/
|
|
package com.sun.opends.sdk.util;
|
|
|
|
import java.io.Serializable;
|
import java.util.LinkedList;
|
import java.util.List;
|
import java.util.Locale;
|
|
|
|
;
|
|
/**
|
* 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.
|
*/
|
public final class MessageBuilder implements Appendable, CharSequence,
|
Serializable
|
{
|
|
private static final long serialVersionUID = -3292823563904285315L;
|
|
/** Used internally to store appended messages. */
|
private final StringBuilder sb = new StringBuilder();
|
|
/** Used internally to store appended messages. */
|
private final List<Message> messages = new LinkedList<Message>();
|
|
/** Used to render the string representation of appended messages. */
|
private final Locale locale;
|
|
|
|
/**
|
* Constructs an instance that will build messages in the default
|
* locale.
|
*/
|
public MessageBuilder()
|
{
|
this(Locale.getDefault());
|
}
|
|
|
|
/**
|
* Constructs an instance that will build messages in the default
|
* locale having an initial message.
|
*
|
* @param message
|
* initial message
|
*/
|
public MessageBuilder(Message message)
|
{
|
this(Locale.getDefault());
|
append(message);
|
}
|
|
|
|
/**
|
* Constructs an instance that will build messages in the default
|
* locale having an initial message.
|
*
|
* @param message
|
* initial message
|
*/
|
public MessageBuilder(String message)
|
{
|
this(Locale.getDefault());
|
append(message);
|
}
|
|
|
|
/**
|
* Constructs an instance from another <code>MessageBuilder</code>.
|
*
|
* @param mb
|
* from which to construct a new message builder
|
*/
|
public MessageBuilder(MessageBuilder mb)
|
{
|
for (Message msg : mb.messages)
|
{
|
this.messages.add(msg);
|
}
|
this.sb.append(sb);
|
this.locale = mb.locale;
|
}
|
|
|
|
/**
|
* Constructs an instance that will build messages in a specified
|
* locale.
|
*
|
* @param locale
|
* used for translating appended messages
|
*/
|
public MessageBuilder(Locale locale)
|
{
|
this.locale = locale;
|
}
|
|
|
|
/**
|
* Append a message to this builder. The string representation of the
|
* locale specifed in the constructor will be stored in this builder.
|
*
|
* @param message
|
* to be appended
|
* @return reference to this builder
|
*/
|
public MessageBuilder append(Message message)
|
{
|
if (message != null)
|
{
|
sb.append(message.toString(locale));
|
messages.add(message);
|
}
|
return this;
|
}
|
|
|
|
/**
|
* Append an integer to this builder.
|
*
|
* @param number
|
* to append
|
* @return reference to this builder
|
*/
|
public MessageBuilder append(int number)
|
{
|
append(String.valueOf(number));
|
return this;
|
}
|
|
|
|
/**
|
* Append an object to this builder.
|
*
|
* @param object
|
* to append
|
* @return reference to this builder
|
*/
|
public MessageBuilder append(Object object)
|
{
|
if (object != null)
|
{
|
append(String.valueOf(object));
|
}
|
return this;
|
}
|
|
|
|
/**
|
* Append a string to this builder.
|
*
|
* @param cs
|
* to append
|
* @return reference to this builder
|
*/
|
public MessageBuilder append(CharSequence cs)
|
{
|
if (cs != null)
|
{
|
sb.append(cs);
|
if (cs instanceof Message)
|
{
|
messages.add((Message) cs);
|
}
|
else
|
{
|
messages.add(Message.raw(cs));
|
}
|
}
|
return this;
|
}
|
|
|
|
/**
|
* Appends a subsequence of the specified character sequence to this
|
* <tt>Appendable</tt>.
|
* <p>
|
* An invocation of this method of the form <tt>out.append(csq, start,
|
* end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in
|
* exactly the same way as the invocation
|
*
|
* <pre>
|
* out.append(csq.subSequence(start, end))
|
* </pre>
|
*
|
* @param csq
|
* The character sequence from which a subsequence will be
|
* appended. If <tt>csq</tt> is <tt>null</tt>, then
|
* characters will be appended as if <tt>csq</tt> contained
|
* the four characters <tt>"null"</tt>.
|
* @param start
|
* The index of the first character in the subsequence
|
* @param end
|
* The index of the character following the last character in
|
* the subsequence
|
* @return A reference to this <tt>Appendable</tt>
|
* @throws IndexOutOfBoundsException
|
* If <tt>start</tt> or <tt>end</tt> are negative,
|
* <tt>start</tt> is greater than <tt>end</tt>, or
|
* <tt>end</tt> is greater than <tt>csq.length()</tt>
|
*/
|
public MessageBuilder append(CharSequence csq, int start, int end)
|
throws IndexOutOfBoundsException
|
{
|
return append(csq.subSequence(start, end));
|
}
|
|
|
|
/**
|
* Appends the specified character to this <tt>Appendable</tt>.
|
*
|
* @param c
|
* The character to append
|
* @return A reference to this <tt>Appendable</tt>
|
*/
|
public MessageBuilder append(char c)
|
{
|
return append(String.valueOf(c));
|
}
|
|
|
|
/**
|
* 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.
|
*
|
* @return a string consisting of exactly this sequence of characters
|
*/
|
public String toString()
|
{
|
return sb.toString();
|
}
|
|
|
|
/**
|
* Returns a string representation of the appended content in the
|
* specific locale. Only <code>Message</code>s appended to this
|
* builder are rendered in the requested locale. Raw strings appended
|
* to this buffer are not translated to different locale.
|
*
|
* @param locale
|
* requested
|
* @return String representation
|
*/
|
public String toString(Locale locale)
|
{
|
StringBuilder sb = new StringBuilder();
|
for (Message m : messages)
|
{
|
sb.append(m.toString(locale));
|
}
|
return sb.toString();
|
}
|
|
|
|
/**
|
* Returns a raw message representation of the appended content.
|
*
|
* @return Message raw message representing builder content
|
*/
|
public Message toMessage()
|
{
|
if (messages.isEmpty())
|
{
|
return Message.EMPTY;
|
}
|
|
StringBuffer fmtString = new StringBuffer();
|
for (int i = 0; i < messages.size(); i++)
|
{
|
fmtString.append("%s");
|
}
|
|
return Message.raw(fmtString, messages.toArray());
|
}
|
|
|
|
/**
|
* Returns the length of the string representation of this builder
|
* using the default locale.
|
*
|
* @return the number of <code>char</code>s in this message
|
*/
|
public int length()
|
{
|
return length(Locale.getDefault());
|
}
|
|
|
|
/**
|
* Returns the <code>char</code> value at the specified index of the
|
* string representation of this builder using the default locale.
|
*
|
* @param index
|
* the index of the <code>char</code> value to be returned
|
* @return the specified <code>char</code> value
|
* @throws IndexOutOfBoundsException
|
* if the <tt>index</tt> argument is negative or not less
|
* than <tt>length()</tt>
|
*/
|
public char charAt(int index) throws IndexOutOfBoundsException
|
{
|
return charAt(Locale.getDefault(), index);
|
}
|
|
|
|
/**
|
* Returns a new <code>CharSequence</code> that is a subsequence of
|
* the string representation of this builder using the default locale.
|
* The subsequence starts with the <code>char</code> value at the
|
* specified index and ends with the <code>char</code> value at index
|
* <tt>end - 1</tt>. The length (in <code>char</code>s) of the
|
* returned sequence is <tt>end - start</tt>, so if
|
* <tt>start == end</tt> then an empty sequence is returned.
|
*
|
* @param start
|
* the start index, inclusive
|
* @param end
|
* the end index, exclusive
|
* @return the specified subsequence
|
* @throws IndexOutOfBoundsException
|
* if <tt>start</tt> or <tt>end</tt> are negative, if
|
* <tt>end</tt> is greater than <tt>length()</tt>, or if
|
* <tt>start</tt> is greater than <tt>end</tt>
|
*/
|
public CharSequence subSequence(int start, int end)
|
throws IndexOutOfBoundsException
|
{
|
return subSequence(Locale.getDefault(), start, end);
|
}
|
|
|
|
/**
|
* Returns the length of the string representation of this builder
|
* using a specific locale.
|
*
|
* @param locale
|
* for which the rendering of this message will be used in
|
* determining the length
|
* @return the number of <code>char</code>s in this message
|
*/
|
public int length(Locale locale)
|
{
|
return toString(locale).length();
|
}
|
|
|
|
/**
|
* Returns the <code>char</code> value at the specified index of the
|
* string representation of this builder using a specific locale.
|
*
|
* @param locale
|
* for which the rendering of this message will be used in
|
* determining the character
|
* @param index
|
* the index of the <code>char</code> value to be returned
|
* @return the specified <code>char</code> value
|
* @throws IndexOutOfBoundsException
|
* if the <tt>index</tt> argument is negative or not less
|
* than <tt>length()</tt>
|
*/
|
public char charAt(Locale locale, int index)
|
throws IndexOutOfBoundsException
|
{
|
return toString(locale).charAt(index);
|
}
|
|
|
|
/**
|
* Returns a new <code>CharSequence</code> that is a subsequence of
|
* the string representation of this builder using a specific locale.
|
* The subsequence starts with the <code>char</code> value at the
|
* specified index and ends with the <code>char</code> value at index
|
* <tt>end - 1</tt>. The length (in <code>char</code>s) of the
|
* returned sequence is <tt>end - start</tt>, so if
|
* <tt>start == end</tt> then an empty sequence is returned.
|
*
|
* @param locale
|
* for which the rendering of this message will be used in
|
* determining the character
|
* @param start
|
* the start index, inclusive
|
* @param end
|
* the end index, exclusive
|
* @return the specified subsequence
|
* @throws IndexOutOfBoundsException
|
* if <tt>start</tt> or <tt>end</tt> are negative, if
|
* <tt>end</tt> is greater than <tt>length()</tt>, or if
|
* <tt>start</tt> is greater than <tt>end</tt>
|
*/
|
public CharSequence subSequence(Locale locale, int start, int end)
|
throws IndexOutOfBoundsException
|
{
|
return toString(locale).subSequence(start, end);
|
}
|
|
}
|
