Package nzilbb.labbcat.server.api

Class Doc

  • public class Doc
extends APIRequestHandler
    Provides CRUD operations for all files/directories under /doc/*.

    This allows for arbitrary documentation of a corpus, using wysiwiki, which allows admin users to create, edit, and delete pages, providing read-only access to others.

    URLs are assumed to identify a file with a ".html" suffix. e.g. GETting http://tld/doc/foo/bar with return the contents of the docs/foo/bar.html file. PUTting to the same URL updates the contents of that file, and DELETEing deletes the file.

    For files that don't exist, 404 is returned, but also the body of a template.html file if the user can edit. This way, the editing user can use the template as a starting point, and PUT the body, with their changes, to create the file.

    GETting http://tld/doc/index returns an HTML document that represents the whole tree of documents and subdirectories, with corresponding <a> links.

    POSTting a file to any URL results in that file being written - i.e. POSTing to the file http://tld/doc/foo/bar.png will result in the creation of a file called http://tld/doc/foo/bar.png, and a relative URL to it is returned as part of the JSON-encoded response to the POST request.

    Author:
    Robert Fromont robert@fromont.net.nz

    • Constructor Detail

      • Doc

        public Doc()
        Constructor

    • Method Detail

      • get

        public void get​(String referer,
                String pathInfo,
                Function<String,​File> realPath,
                OutputStream out,
                Consumer<Long> expiresHeader,
                Consumer<String> contentType,
                Consumer<String> contentEncoding,
                Consumer<Integer> httpStatus,
                Consumer<String> redirectUrl)
        GET handler: Return the given HTML document, or a blank template if it doesn't exist yet.

        If the Accept request header includes "application/json", then the response is a JSON-encoded representation of the existing file/directory structure for this document, including peers, ancestors, and ancestor peers. This allows the wysiwiki page to present a navigation tree to the user.

        Parameters:
        referer - The request referrer.
        pathInfo - The URL path.
        realPath - Function for translating an absolute URL path into a File.
        out - Response body output stream.
        contentType - Receives the content type for specification in the response headers.
        contentEncoding - Receives content character encoding for specification in the response headers.
        httpStatus - Receives the response status code, in case or error.
        redirectUrl - Receives a URL for the request to be redirected to.

      • put

        public void put​(String pathInfo,
                Function<String,​File> realPath,
                RequestParameters parameters,
                InputStream requestBody,
                OutputStream out,
                Consumer<String> contentType,
                Consumer<String> contentEncoding,
                Consumer<Integer> httpStatus)
        PUT handler: Adds or updates an HTML document, or if the "move" parameter is specified, the document's entry is moved in the index (in which case the HTML document itself is not updated).
        Parameters:
        pathInfo - The URL path.
        realPath - Function for translating an absolute URL path into a File.
        requestBody - Stream supplying the body of the request.
        out - Stream for writing the response.
        contentType - Consumer for receiving the output content type..
        contentEncoding - Receives content character encoding for specification in the response headers.
        httpStatus - Receives the response status code, in case or error.

      • delete

        public void delete​(String pathInfo,
                   Function<String,​File> realPath,
                   OutputStream out,
                   Consumer<String> contentType,
                   Consumer<String> contentEncoding,
                   Consumer<Integer> httpStatus)
        DELETE handler: Delete the given HTML document.
        Parameters:
        pathInfo - The URL path.
        realPath - Function for translating an absolute URL path into a File.
        out - Response body output stream.
        contentType - Receives the content type for specification in the response headers.
        contentEncoding - Receives content character encoding for specification in the
        httpStatus - Receives the response status code, in case or error.

      • post

        public void post​(String pathInfo,
                 Function<String,​File> realPath,
                 RequestParameters parameters,
                 OutputStream out,
                 Consumer<String> contentType,
                 Consumer<String> contentEncoding,
                 Consumer<Integer> httpStatus)
        POST handler: for saving images and other assets.
        Parameters:
        pathInfo - The URL path.
        realPath - Function for translating an absolute URL path into a File.
        parameters - Request parameter map.
        out - Stream for writing the response.
        contentType - Consumer for receiving the output content type..
        contentEncoding - Receives content character encoding for specification in the response headers.
        httpStatus - Receives the response status code, in case or error.

      • options

        public String options()
        OPTIONS handler: specifies what HTML methods are allowed, depending on the user access.

      • title

        public static String title​(File html)
        Gets the title of the given document file.
        Parameters:
        html - A .html document.
        Returns:
        The contents of the <title> tag in the file, or the file name without the suffix, if there is none.