Package org.czeal.urireference

Class URIReferenceBuilder

java.lang.Object

org.czeal.urireference.URIReferenceBuilder

public class URIReferenceBuilder
extends Object

A builder class for constructing URI references.

This class provides a fluent API to build a URIReference object incrementally by setting its various components such as scheme, userinfo, host, port, path, query, and fragment.

This builder supports both absolute and relative URI references.

Examples:

 //---------------------------------------------------------------------------
 // Build a URI reference.
 //---------------------------------------------------------------------------
 URIReference uriRef = new URIReferenceBuilder()
                           .setScheme("http")
                           .setHost("example.com")
                           .setPath("/a/b/c")
                           .appendQueryParam("k1", "v1")
                           .build();

 System.out.println(uriRef.toString());                          // "http://example.com/a/b/c?k1=v1"
 System.out.println(uriRef.getScheme());                         // "http"
 System.out.println(uriRef.getAuthority());                      // "example.com"
 System.out.println(uriRef.getUserinfo());                       // null
 System.out.println(uriRef.getAuthority().getHost().getType());  // "REGNAME"
 System.out.println(uriRef.getAuthority().getHost().getValue()); // "example.com"
 System.out.println(uriRef.getPort());                           // -1
 System.out.println(uriRef.getPath());                           // "/a/b/c"
 System.out.println(uriRef.getQuery());                          // "k1=v1"
 System.out.println(uriRef.getFragment());                       // null


 //---------------------------------------------------------------------------
 // Build a URI reference from another URI reference.
 //---------------------------------------------------------------------------
 URIReference uriRef = URIReferenceBuilder
                           .fromURIReference("http://example.com/a/b/c?k1=v1")
                           .appendPath("d", "e", "f")
                           .appendQueryParam("k2", "v2")
                           .build();

 System.out.println(uriRef.toString());                          // "http://example.com/a/b/c/d/e/f?k1=v1&k2=v2"
 System.out.println(uriRef.getScheme());                         // "http"
 System.out.println(uriRef.getAuthority().toString());           // "example.com"
 System.out.println(uriRef.getUserinfo());                       // null
 System.out.println(uriRef.getAuthority().getHost().getType());  // "REGNAME"
 System.out.println(uriRef.getAuthority().getHost().getValue()); // "example.com"
 System.out.println(uriRef.getPort());                           // -1
 System.out.println(uriRef.getPath());                           // "/a/b/c/d/e/f"
 System.out.println(uriRef.getQuery());                          // "k1=v1&k2=&v2"
 System.out.println(uriRef.getFragment());                       // null

 

Author:

Hideki Ikeda

See Also:

RFC 3986 - Uniform Resource Identifier (URI): Generic Syntax

Constructor Summary

Constructors

Constructor	Description
URIReferenceBuilder()

Method Summary

Modifier and Type	Method	Description
URIReferenceBuilder	appendPathSegments(String... segment)	Appends a path segment.
URIReferenceBuilder	appendQueryParam(String key, String value)	Appends a new query parameter to the resultant URI reference.
URIReference	build()	Builds a URI reference.
static URIReferenceBuilder	fromURIReference(String uriRef)	Creates a URIReferenceBuilder instance with a given string representing a URI reference.
static URIReferenceBuilder	fromURIReference(URIReference uriRef)	Creates a URIReferenceBuilder instance with a given string representing a URI reference.
URIReferenceBuilder	removeQueryParam(String key)	Removes the query parameter(s) specified by a key.
URIReferenceBuilder	replaceQueryParam(String key, String value)	Replaces the value(s) of the query parameter(s) specified by the key with a new value.
URIReferenceBuilder	setAuthorityRequired(boolean authorityRequired)	Determines whether or not the authority is required in the resultant URI reference.
URIReferenceBuilder	setCharset(Charset charset)	Sets the charset used in the resultant URI reference.
URIReferenceBuilder	setFragment(String fragment)	Sets the fragment.
URIReferenceBuilder	setHost(String host)	Sets the host.
URIReferenceBuilder	setPath(String path)	Sets the path.
URIReferenceBuilder	setPort(int port)	Sets the port.
URIReferenceBuilder	setQuery(String query)	Sets the query.
URIReferenceBuilder	setScheme(String scheme)	Sets the scheme.
URIReferenceBuilder	setUserinfo(String userinfo)	Sets the userinfo.
URIReferenceBuilder	uriRef(URIReference uriRef)	Sets information about a given URIReferenceBuilder instance.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

URIReferenceBuilder

public URIReferenceBuilder()

Method Detail

fromURIReference

public static URIReferenceBuilder fromURIReference(String uriRef)

Creates a URIReferenceBuilder instance with a given string representing a URI reference. This method copies the following information to the created instance:

• charset
• scheme
• userinfo
• host
• port
• query
• fragment

Note that this method works as if invoking it were equivalent to evaluating the following expression:

 fromURIReference(URIReference.parse(uriRef))
 

Parameters:

uriRef - A string representing a URI reference.

Returns:

A URIReferenceBuilder instance initialized with the given URI reference information.

fromURIReference

public static URIReferenceBuilder fromURIReference(URIReference uriRef)

Creates a URIReferenceBuilder instance with a given string representing a URI reference. This method copies the following information to the created instance:

• charset
• scheme
• userinfo
• host
• port
• query
• fragment

Note that this method works as if invoking it were equivalent to evaluating the following expression:

 new URIReferenceBuilder().uriRef(uriRef)
 

Parameters:

uriRef - A URIReference instance.

Returns:

A URIReferenceBuilder instance initialized with the given URI reference information.

uriRef

public URIReferenceBuilder uriRef(URIReference uriRef)

Sets information about a given URIReferenceBuilder instance. Specifically, it copies the following information from the given URIReferenceBuilder instance to this instance.

• charset
• scheme
• userinfo
• host
• port
• query
• fragment

Parameters:

uriRef - A URIReference instance.

Returns:

this object.

setCharset

public URIReferenceBuilder setCharset(Charset charset)

Sets the charset used in the resultant URI reference.

This method replaces existing charset value with the given value.

Parameters:

charset - The charset.

Returns:

this object.

setScheme

public URIReferenceBuilder setScheme(String scheme)

Sets the scheme.

This method replaces existing scheme value with the given value.

Parameters:

scheme - The scheme of the resultant URI reference. Specifying null for this property unsets the scheme.

Returns:

this object.

setUserinfo

public URIReferenceBuilder setUserinfo(String userinfo)

Sets the userinfo.

This method replaces existing userinfo value with the given value.

Parameters:

userinfo - The userinfo of the resultant URI reference. Specifying null for this property unsets the userinfo.

Returns:

this object.

setHost

public URIReferenceBuilder setHost(String host)

Sets the host.

This method replaces existing host value with the given value.

Parameters:

host - The host of the resultant URI reference. Specifying null for this property unsets the host.

Returns:

this object.

setPort

public URIReferenceBuilder setPort(int port)

Sets the port.

This method replaces existing port value with the given value.

Parameters:

port - The port of the resultant URI reference. Specifying null for this property unsets the port.

Returns:

this object.

setPath

public URIReferenceBuilder setPath(String path)

Sets the path.

This method replaces existing path value with the given value.

Parameters:

path - The path of the resultant URI reference. Specifying null for this property unsets the path.

Returns:

this object.

setQuery

public URIReferenceBuilder setQuery(String query)

Sets the query.

This method replaces the existing query value with the given value.

Parameters:

query - The query of the resultant URI reference. Specifying null for this property unsets the query.

Returns:

this object.

setFragment

public URIReferenceBuilder setFragment(String fragment)

Sets the fragment.

This method replaces existing fragment value with the given value.

Parameters:

fragment - The fragment of the resultant URI reference. Specifying null for this property unsets the fragment.

Returns:

this object.

setAuthorityRequired

public URIReferenceBuilder setAuthorityRequired(boolean authorityRequired)

Determines whether or not the authority is required in the resultant URI reference.

Parameters:

authorityRequired - If true, the authority part is present in the resultant URI reference; otherwise, it will be omitted.

Returns:

this object.

appendQueryParam

public URIReferenceBuilder appendQueryParam(String key,
                                            String value)

Appends a new query parameter to the resultant URI reference.

Parameters:

key - The key of the new query parameter.

value - The value of the new query parameter.

Returns:

this object.

replaceQueryParam

public URIReferenceBuilder replaceQueryParam(String key,
                                             String value)

Replaces the value(s) of the query parameter(s) specified by the key with a new value.

Parameters:

key - The key of the query parameter(s) whose value(s) is to be replaced.

value - A new value of the new query parameter.

Returns:

this object.

removeQueryParam

public URIReferenceBuilder removeQueryParam(String key)

Removes the query parameter(s) specified by a key.

Parameters:

key - The key of the query parameter(s) to be removed.

Returns:

this object.

appendPathSegments

public URIReferenceBuilder appendPathSegments(String... segment)

Appends a path segment.

Parameters:

segment - A path segment.

Returns:

this object.

build

public URIReference build()

Builds a URI reference.

Returns:

An URIReference object representing the resultant URI reference.