UrlParams: A Builder class to construct URL parameters in Java

UrlParams.java

import java.io.UnsupportedEncodingException;
import java.net.URLEncoder;
import java.util.ArrayList;
import java.util.List;

/**
 * A class to create URL parameters in a builder-like fashion
 *
 * @author Inderjeet Singh
 */
public class UrlParams {
    // Using two lists instead of a map to ensure that parameters are printed in the order
    // they were put. This also allows a key to appear multiple times.
    private final List<String> keys = new ArrayList<String>();
    private final List<String> values = new ArrayList<String>();

    /** Adds the URL parameter if and only if both key and value are not empty */
    public UrlParams add(String key, String value) {
        if (!isNullOrWhitespace(key) && !isNullOrWhitespace(value)) {
            keys.add(key);
            values.add(value);
        }
        return this;
    }

    public UrlParams add(String key, boolean value) {
        keys.add(key);
        values.add(String.valueOf(value));
        return this;
    }

    public UrlParams add(String key, List<String> strings) {
        return add(key, toCsvString(strings));
    }

    /** appends the parameters to a base URL in the form ?a=b&c=d */
    public void appendToUrl(StringBuilder sb) {
        try {
            boolean first = true;
            for (int i = 0; i < keys.size(); ++i) {
                if (first) {
                    first = false;
                    sb.append('?');
                } else {
                    sb.append('&');
                }
                sb.append(URLEncoder.encode(keys.get(i), "UTF-8"));
                sb.append('=');
                sb.append(URLEncoder.encode(values.get(i), "UTF-8"));
            }
        } catch (UnsupportedEncodingException e) {
            throw new RuntimeException(e);
        }
    }

    @Override
    public String toString() {
        StringBuilder sb = new StringBuilder();
        appendToUrl(sb);
        return sb.toString();
    }

    private static boolean isNullOrWhitespace(String str) {
        return str == null || str.trim().isEmpty();
    }  

    private static String toCsvString(List<String> strings) {
        String value = null;
        if (strings != null) {
            StringBuilder sb = new StringBuilder();
            boolean first = true;
            for (String str : strings) {
                if (first) {
                    first = false;
                } else {
                    sb.append(",");
                }
                sb.append(str);
            }
            value = sb.toString();
        }
        return value;
    }
}

UrlParamsTest.java

import static org.junit.Assert.assertEquals;
import static org.junit.Assert.assertTrue;

import java.util.ArrayList;
import java.util.List;

import org.junit.Test;

/**
 * Unit tests for {@link UrlParams}.
 *
 * @author Inderjeet Singh
 */
public class UrlParamsTest {
    @Test
    public void testEscapedCharacters() {
        UrlParams params = new UrlParams();
        assertEquals("", params.toString());

        params = new UrlParams().add("a", "b");
        assertEquals("?a=b", params.toString());

        params = new UrlParams().add("a", "b").add("c", "d");
        assertEquals("?a=b&c=d", params.toString());

        // Test the space character
        params = new UrlParams().add("c", "Simple Test");
        String escaped = params.toString();
        assertTrue(escaped.equals("?c=Simple+Test") || escaped.equals("?c=Simple%20Test"));

        // Test escaped characters
        params = new UrlParams().add("c=", "ab,cd/ef%:");
        assertEquals("?c%3D=ab%2Ccd%2Fef%25%3A", params.toString());
    }

    @Test
    public void testValueAsStringList() {
        UrlParams params = new UrlParams();
        List<String> strings = new ArrayList<String>();
        params.add("foo", strings);
        assertEquals("", params.toString()); // array is empty so shouldn't go out as value
        strings.add("a");
        strings.add("b & c");
        params.add("bar", strings);
        assertEquals("?bar=a%2Cb+%26+c", params.toString());
    }
}