net.sf.javaprinciples.resource.ResourceFactory Maven / Gradle / Ivy

Go to download

Show more of this group Show more artifacts with this name
Show all versions of resource-handling-api Show documentation

There is a newer version: 3.0.3

Show newest version

package net.sf.javaprinciples.resource;

/**
 *
 * @author wslade
 * @param  - content type of resource
 */
public interface ResourceFactory
{
    /**
     *
     * @param identifier A non-null URN
     * @return A resource matching the identifier, may be null if not available.
     * @throws ResourceException On any error encountered.
     */
    public Resource getResource(ResourceIdentifier identifier) throws ResourceException;

    /**
     * Put a Resource representation to the server in response to a PUT request.
     * PUT requests typically update an existing representation, or in cases of
     * Resource creation, this method is used where the client is able to construct a
     * valid URI.
     * @param identifier The identifier of the Resource to be updated / created.
     * @param resource The representation to be put onto the server.
     * @return ResourceIdentifier, may be null.
     * @throws ResourceException On any error encountered.
     */
    ResourceIdentifier putResource(ResourceIdentifier identifier, Resource resource) throws ResourceException;

    /**
     * Put a Resource representation to the server in response to a POST request.
     * POST requests are generally used to create a new Resource on the server, when
     * the server is responsible for creating the Resource URI. A file upload service is
     * a good example of using this method.
     * @param resource The Resource representation to be put onto the server.
     * @return The URI created by the server for the new Resource.
     * @throws ResourceException On any error encountered.
     */
    ResourceIdentifier putResource(Resource resource) throws ResourceException;
}