| /* |
| * Copyright (C) 2010-2013 The University of Manchester |
| * |
| * See the file "LICENSE" for license terms. |
| */ |
| package org.taverna.server.master.rest; |
| |
| import static java.util.Collections.unmodifiableList; |
| import static javax.ws.rs.core.MediaType.WILDCARD; |
| import static org.taverna.server.master.common.Roles.USER; |
| import static org.taverna.server.master.rest.ContentTypes.BYTES; |
| import static org.taverna.server.master.rest.ContentTypes.JSON; |
| import static org.taverna.server.master.rest.ContentTypes.URI_LIST; |
| import static org.taverna.server.master.rest.ContentTypes.XML; |
| import static org.taverna.server.master.rest.ContentTypes.ZIP; |
| |
| import java.io.InputStream; |
| import java.net.URI; |
| import java.util.List; |
| |
| import javax.annotation.Nonnull; |
| import javax.annotation.security.RolesAllowed; |
| import javax.ws.rs.Consumes; |
| import javax.ws.rs.DELETE; |
| import javax.ws.rs.GET; |
| import javax.ws.rs.OPTIONS; |
| import javax.ws.rs.POST; |
| import javax.ws.rs.PUT; |
| import javax.ws.rs.Path; |
| import javax.ws.rs.PathParam; |
| import javax.ws.rs.Produces; |
| import javax.ws.rs.core.Context; |
| import javax.ws.rs.core.HttpHeaders; |
| import javax.ws.rs.core.PathSegment; |
| import javax.ws.rs.core.Response; |
| import javax.ws.rs.core.UriInfo; |
| import javax.ws.rs.core.Variant; |
| |
| import org.apache.cxf.jaxrs.model.wadl.Description; |
| import org.taverna.server.master.exceptions.FilesystemAccessException; |
| import org.taverna.server.master.exceptions.NoDirectoryEntryException; |
| import org.taverna.server.master.exceptions.NoUpdateException; |
| import org.taverna.server.master.interfaces.Directory; |
| import org.taverna.server.master.interfaces.File; |
| |
| /** |
| * Representation of how a workflow run's working directory tree looks. |
| * |
| * @author Donal Fellows |
| */ |
| @RolesAllowed(USER) |
| @Produces({ XML, JSON }) |
| @Consumes({ XML, JSON }) |
| @Description("Representation of how a workflow run's working directory tree looks.") |
| public interface TavernaServerDirectoryREST { |
| /** |
| * Get the working directory of the workflow run. |
| * |
| * @param ui |
| * About how this method was called. |
| * @return A description of the working directory. |
| * @throws FilesystemAccessException |
| */ |
| @GET |
| @Path("/") |
| @Description("Describes the working directory of the workflow run.") |
| @Nonnull |
| DirectoryContents getDescription(@Nonnull @Context UriInfo ui) |
| throws FilesystemAccessException; |
| |
| /** Get an outline of the operations supported. */ |
| @OPTIONS |
| @Path("{path:.*}") |
| @Description("Produces the description of the files/directories' baclava operations.") |
| Response options(@PathParam("path") List<PathSegment> path); |
| |
| /** |
| * Gets a description of the named entity in or beneath the working |
| * directory of the workflow run, which may be either a {@link Directory} or |
| * a {@link File}. |
| * |
| * @param path |
| * The path to the thing to describe. |
| * @param ui |
| * About how this method was called. |
| * @param headers |
| * About what the caller was looking for. |
| * @return An HTTP response containing a description of the named thing. |
| * @throws NoDirectoryEntryException |
| * If the name of the file or directory can't be looked up. |
| * @throws FilesystemAccessException |
| * If something went wrong during the filesystem operation. |
| * @throws NegotiationFailedException |
| * If the content type being downloaded isn't one that this |
| * method can support. |
| */ |
| @GET |
| @Path("{path:.+}") |
| @Produces({ XML, JSON, BYTES, ZIP, WILDCARD }) |
| @Description("Gives a description of the named entity in or beneath the " |
| + "working directory of the workflow run (either a Directory or File).") |
| @Nonnull |
| Response getDirectoryOrFileContents( |
| @Nonnull @PathParam("path") List<PathSegment> path, |
| @Nonnull @Context UriInfo ui, @Nonnull @Context HttpHeaders headers) |
| throws NoDirectoryEntryException, FilesystemAccessException, |
| NegotiationFailedException; |
| |
| /** |
| * Creates a directory in the filesystem beneath the working directory of |
| * the workflow run, or creates or updates a file's contents, where that |
| * file is in or below the working directory of a workflow run. |
| * |
| * @param parent |
| * The directory to create the directory in. |
| * @param operation |
| * What to call the directory to create. |
| * @param ui |
| * About how this method was called. |
| * @return An HTTP response indicating where the directory was actually made |
| * or what file was created/updated. |
| * @throws NoDirectoryEntryException |
| * If the name of the containing directory can't be looked up. |
| * @throws NoUpdateException |
| * If the user is not permitted to update the run. |
| * @throws FilesystemAccessException |
| * If something went wrong during the filesystem operation. |
| */ |
| @POST |
| @Path("{path:.*}") |
| @Description("Creates a directory in the filesystem beneath the working " |
| + "directory of the workflow run, or creates or updates a file's " |
| + "contents, where that file is in or below the working directory " |
| + "of a workflow run.") |
| @Nonnull |
| Response makeDirectoryOrUpdateFile( |
| @Nonnull @PathParam("path") List<PathSegment> parent, |
| @Nonnull MakeOrUpdateDirEntry operation, |
| @Nonnull @Context UriInfo ui) throws NoUpdateException, |
| FilesystemAccessException, NoDirectoryEntryException; |
| |
| /** |
| * Creates or updates a file in a particular location beneath the working |
| * directory of the workflow run. |
| * |
| * @param file |
| * The path to the file to create or update. |
| * @param referenceList |
| * Location to get the file's contents from. Must be |
| * <i>publicly</i> readable. |
| * @param ui |
| * About how this method was called. |
| * @return An HTTP response indicating what file was created/updated. |
| * @throws NoDirectoryEntryException |
| * If the name of the containing directory can't be looked up. |
| * @throws NoUpdateException |
| * If the user is not permitted to update the run. |
| * @throws FilesystemAccessException |
| * If something went wrong during the filesystem operation. |
| */ |
| @POST |
| @Path("{path:(.*)}") |
| @Consumes(URI_LIST) |
| @Description("Creates or updates a file in a particular location beneath the " |
| + "working directory of the workflow run with the contents of a " |
| + "publicly readable URL.") |
| @Nonnull |
| Response setFileContentsFromURL(@PathParam("path") List<PathSegment> file, |
| List<URI> referenceList, @Context UriInfo ui) |
| throws NoDirectoryEntryException, NoUpdateException, |
| FilesystemAccessException; |
| |
| /** |
| * Creates or updates a file in a particular location beneath the working |
| * directory of the workflow run. |
| * |
| * @param file |
| * The path to the file to create or update. |
| * @param contents |
| * Stream of bytes to set the file's contents to. |
| * @param ui |
| * About how this method was called. |
| * @return An HTTP response indicating what file was created/updated. |
| * @throws NoDirectoryEntryException |
| * If the name of the containing directory can't be looked up. |
| * @throws NoUpdateException |
| * If the user is not permitted to update the run. |
| * @throws FilesystemAccessException |
| * If something went wrong during the filesystem operation. |
| */ |
| @PUT |
| @Path("{path:(.*)}") |
| @Consumes({ BYTES, WILDCARD }) |
| @Description("Creates or updates a file in a particular location beneath the " |
| + "working directory of the workflow run.") |
| @Nonnull |
| Response setFileContents(@PathParam("path") List<PathSegment> file, |
| InputStream contents, @Context UriInfo ui) |
| throws NoDirectoryEntryException, NoUpdateException, |
| FilesystemAccessException; |
| |
| /** |
| * Deletes a file or directory that is in or below the working directory of |
| * a workflow run. |
| * |
| * @param path |
| * The path to the file or directory. |
| * @return An HTTP response to the method. |
| * @throws NoUpdateException |
| * If the user is not permitted to update the run. |
| * @throws FilesystemAccessException |
| * If something went wrong during the filesystem operation. |
| * @throws NoDirectoryEntryException |
| * If the name of the file or directory can't be looked up. |
| */ |
| @DELETE |
| @Path("{path:.*}") |
| @Description("Deletes a file or directory that is in or below the working " |
| + "directory of a workflow run.") |
| @Nonnull |
| Response destroyDirectoryEntry(@PathParam("path") List<PathSegment> path) |
| throws NoUpdateException, FilesystemAccessException, |
| NoDirectoryEntryException; |
| |
| /** |
| * Exception thrown to indicate a failure by the client to provide an |
| * acceptable content type. |
| * |
| * @author Donal Fellows |
| */ |
| @SuppressWarnings("serial") |
| public static class NegotiationFailedException extends Exception { |
| public List<Variant> accepted; |
| |
| public NegotiationFailedException(String msg, List<Variant> accepted) { |
| super(msg); |
| this.accepted = unmodifiableList(accepted); |
| } |
| } |
| } |