Package org.opencastproject.runtimeinfo.rest

Class RestDocData

  • public class RestDocData
extends org.opencastproject.util.doc.DocData
    This is the document model class which holds the data about a set of rest endpoints.

    • Field Detail

      • PATH_PARAM_COUNTING_REGEX

        public static final String PATH_PARAM_COUNTING_REGEX
        Regular expression used to count the number of path parameters in a path.
        See Also:
        Constant Field Values

      • holders

        protected List<RestEndpointHolderData> holders
        List of RestEndpointHolderData which each stores a group of endpoints. Currently there are 2 groups, READ group and WRITE group.

    • Constructor Detail

      • RestDocData

        public RestDocData​(String name,
                   String title,
                   String url,
                   String[] notes)
            throws IllegalArgumentException
        Create the base data object for creating REST documentation.
        Parameters:
        name - the name of the set of rest endpoints (must be alphanumeric (includes _) and no spaces or special chars)
        title - [OPTIONAL] the title of the documentation
        url - this is the absolute base URL for this endpoint, do not include the trailing slash (e.g. /workflow)
        notes - [OPTIONAL] an array of notes to add into the end of the documentation
        Throws:
        IllegalArgumentException - if the url is null or empty

    • Method Detail

      • toMap

        public Map<String,​Object> toMap()
                               throws IllegalStateException
        Verify the integrity of this object. If its data is verified to be okay, it return a map representation of this RestDocData object.
        Overrides:
        toMap in class org.opencastproject.util.doc.DocData
        Returns:
        a map representation of this RestDocData object if this object passes the verification
        Throws:
        IllegalStateException - if any path parameter is not present in the endpoint's path

      • getDefaultTemplatePath

        public String getDefaultTemplatePath()
        Gets the path to the default template (a .xhtml file).
        Overrides:
        getDefaultTemplatePath in class org.opencastproject.util.doc.DocData
        Returns:
        the path to the default template file

      • toString

        public String toString()
        Returns a string representation of this object.
        Overrides:
        toString in class Object
        Returns:
        a string representation of this object

      • setAbstract

        public void setAbstract​(String abstractText)
        Creates an abstract section which is displayed at the top of the documentation page.
        Parameters:
        abstractText - any text to place at the top of the document, can be html markup but must be valid

      • isValidPath

        public static boolean isValidPath​(String path)
        Validates paths: VALID: /sample , /sample/{thing} , /{my}/{path}.xml , /my/fancy_path/is/{awesome}.{FORMAT} INVALID: sample, /sample/, /sa#$%mple/path
        Parameters:
        path - the path value to check
        Returns:
        true if this path is valid, false otherwise

      • addEndpoint

        public void addEndpoint​(org.opencastproject.util.doc.rest.RestQuery restQuery,
                        Class<?> returnType,
                        javax.ws.rs.Produces produces,
                        String httpMethodString,
                        javax.ws.rs.Path path)
        Add an endpoint to the Rest documentation.
        Parameters:
        restQuery - the RestQuery annotation type storing information of an endpoint
        returnType - the return type for this endpoint. If this is XmlRootElement or XmlRootElement, the XML schema for the class will be made available to clients
        produces - the return type(s) of this endpoint, values should be constants from javax.ws.rs.core.MediaType or ExtendedMediaType (org.opencastproject.util.doc.rest.ExtendedMediaType).
        httpMethodString - the HTTP method of this endpoint (e.g. GET, POST)
        path - the path of this endpoint