com.strategicgains.hyperexpress.builder.LinkBuilder Maven / Gradle / Ivy

Go to download
Show more of this group Show more artifacts with this name
Show all versions of HyperExpress-Core Show documentation
The newest version!
package com.strategicgains.hyperexpress.builder;

import com.strategicgains.hyperexpress.domain.Link;

/**
 * Build LinkDefinition instances from a URL pattern, binding URL tokens to
 * actual values. Uses UrlBuilder to build the href or URL portion of the 
 * Link.
 * 
 * @author toddf
 * @since May 5, 2014
 * @see UrlBuilder
 */
public interface LinkBuilder
{
	/**
	 * Set the prefix portion of the URL which is to be pre-pended to the URL
	 * pattern.
	 * 
	 * Optional, as the URL pattern may contain everything. However, this is
	 * provided as a convenience so consumers don't have to perform their own
	 * concatenation to pass in the entire URL pattern string to the constructor.
	 * 

	 * For example: 'http://www.example.com:8080'
	 * 
	 * @param baseUrl the string that will prefix the URL pattern
	 * @return this LinkBuilder instance to facilitate method chaining.
	 */
	public LinkBuilder baseUrl(String url);

	/**
	 * Add an optional query-string segment to this LinkBuilder.
	 * 

	 * If all of the tokens in the query-string are bound, the segment is included
	 * in the generated URL string during build().  However, if there are unbound
	 * tokens in the resulting query-string segment, it is not included in the
	 * generated URL string.
	 * 

	 * Do not include any question mark ("?") or ampersand ("&") in the query-string
	 * segment.
	 * 
	 * @param query a query-string segment to optionally include.
	 * @return this LinkBuilder instance to facilitate method chaining.
	 */
	public LinkBuilder withQuery(String query);

	/**
	 * Remove all attribute settings from this UrlBuilder.
	 * Properties such as 'rel', 'href', 'type' and 'title'
	 * are removed. Does not clear queries or URL-related
	 * properties, namely baseUrl or URl pattern.
	 */
	public void clearAttributes();

	/**
	 * Remove the query-string segments from this UrlBuilder.
	 */
	public void clearQueries();

	/**
	 * Retrieve the URL pattern associated with this link builder.
	 * 
	 * @return the URL pattern or null.
	 */
	public String urlPattern();

	/**
	 * Set the URL pattern associated with this link builder.
	 * 
	 * @param pattern the new URL pattern.
	 * @return this LinkBuilder instance to facilitate method chaining.
	 */
	public LinkBuilder urlPattern(String pattern);

	/**
	 * Set the 'rel' or relation-type value for links generated by this LinkBuilder.
	 * 
	 * @param rel the relation-type name.
	 * @return this LinkBuilder instance to facilitate method chaining.
	 */
	public LinkBuilder rel(String rel);

	/**
	 * Retrieve the 'rel' or relation-type name.
	 * 
	 * @return the relation-type name, or null if the value is not set.
	 */
	public String rel();

	/**
	 * Set the 'title' value of links generated by this LinkBuilder.
	 * 
	 * @param title the title for generated links.
	 * @return this LinkBuilder instance to facilitate method chaining.
	 */
	public LinkBuilder title(String title);

	/**
	 * Retrieve the 'title' value.
	 * 
	 * @return the link title, or null if the value is not set.
	 */
	public String title();

	/**
	 * Set the 'type' value of links generated by this LinkBuilder.
	 * 
	 * @param type the type for generated links.
	 * @return this LinkBuilder instance to facilitate method chaining.
	 */
	public LinkBuilder type(String type);

	/**
	 * Retrieve the 'type'.
	 * 
	 * @return the type of links, or null if the value is not set.
	 */
	public String type();

	/**
	 * Retrieve the value of an arbitrary named property value.
	 * 
	 * @param name the name of the property to retrieve.
	 * @return the value for the give name, or null if the property is not set.
	 */
	public String get(String name);

	/**
	 * Set an arbitrary named value for links generated by this LinkBuilder.
	 * If a property of the same name was previously-set, including 'rel', 'title'
	 * or 'type', it will be overwritten.
	 * 
	 * If the value is null, the property is removed, if it was set before.
	 * 
	 * @param name the name of a property.
	 * @param value the value of the property given by name.
	 * @return this LinkBuilder instance to facilitate method chaining.
	 */
	public LinkBuilder set(String name, String value);

	/**
	 * Build a Link instance.
	 * 
	 * @throws LinkBuilderException if the LinkBuilder is in a state to build an invalid
	 * LinkDefintion.
	 */
	public Link build();

	/**
	 * Build a Link instance.
	 * 
	 * @param tokenResolver a TokenResolver with token bindings.
	 * @return a new Link instance
	 * @throws LinkBuilderException if the LinkBuilder is in a state to build an invalid
	 * LinkDefintion.
	 */
	public Link build(TokenResolver tokenResolver);

	/**
	 * Build a Link instance.
	 * 
	 * @param object an object that the token resolver can use to extract values from.
	 * @param tokenResolver a TokenResolver with token bindings.
	 * @return a new Link instance
	 * @throws LinkBuilderException if the LinkBuilder is in a state to build an invalid
	 * LinkDefintion.
	 */
	public Link build(Object object, TokenResolver tokenResolver);
}