Package org.opencastproject.runtimeinfo.rest

Class RestEndpointData

    • Constructor Detail

      • RestEndpointData

        public RestEndpointData​(Class<?> returnType,
                        String name,
                        String httpMethod,
                        String path,
                        String description)
                 throws IllegalArgumentException
        Create a new basic endpoint, you should use the add methods to fill in the rest of the information about the endpoint data
        Parameters:
        returnType - the endpoint's return type
        name - the endpoint's name (this should be unique in the same type of endpoints)
        httpMethod - the HTTP method used for this endpoint
        path - the path for this endpoint (e.g. /search OR /add/{id})
        description - [optional] the description of this endpoint
        Throws:
        IllegalArgumentException - if name is null, name is not alphanumeric, method is null, path is null or path is not valid.

    • Method Detail

      • toString

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

      • addBodyParam

        public RestParamData addBodyParam​(org.opencastproject.util.doc.rest.RestParameter restParam)
        Adds a body parameter to this endpoint. Once added, the body parameter becomes a required parameter.
        Parameters:
        restParam - a RestParameter annotation object corresponding to the body parameter
        Returns:
        the new RestParamData object in case you want to set attributes

      • addPathParam

        public void addPathParam​(RestParamData param)
                  throws IllegalStateException
        Adds a path parameter for this endpoint, this would be a parameter which is passed as part of the path (e.g. /my/path/{param}) and thus must use a name which is safe to be placed in a URL and does not contain a slash (/)
        Parameters:
        param - the path parameter to add
        Throws:
        IllegalStateException - if the type of the path parameter is FILE or TEXT

      • addRequiredParam

        public void addRequiredParam​(RestParamData param)
                      throws IllegalStateException
        Adds a required form parameter for this endpoint, this would be a parameter which is passed encoded as part of the request body (commonly referred to as a post or form parameter).
        WARNING: This should generally be reserved for endpoints which are used for processing, it is better to use path params unless the required parameter is not part of an identifier for the resource.
        Parameters:
        param - the required parameter to add
        Throws:
        IllegalStateException

      • addOptionalParam

        public void addOptionalParam​(RestParamData param)
        Adds an optional parameter for this endpoint, this would be a parameter which is passed in the query string (for GET) or encoded as part of the body otherwise (often referred to as a post or form parameter).
        Parameters:
        param - the optional parameter to add

      • addFormat

        public void addFormat​(RestFormatData format)
        Adds a format for the return data for this endpoint.
        Parameters:
        format - a RestFormatData object

      • addStatus

        public void addStatus​(org.opencastproject.util.doc.rest.RestResponse restResponse)
        Adds a response status for this endpoint.
        Parameters:
        restResponse - a RestResponse object containing the HTTP response code and description

      • setTestForm

        public void setTestForm​(RestFormData form)
        Sets the test form for this endpoint, if this is null then no test form is rendered for this endpoint.
        Parameters:
        form - the test form object (null to clear the form)

      • isGetMethod

        public boolean isGetMethod()
        Returns whether this endpoint's HTTP method is GET
        Returns:
        true if this endpoint method is GET, otherwise false

      • getQueryString

        public String getQueryString()
        Returns the URL-encoded query string for a GET endpoint.
        Returns:
        the calculated query string for a GET endpoint (e.g. ?blah=1), will be urlencoded for html display

      • getName

        public String getName()
        Gets the name of this endpoint.
        Returns:
        the name of this endpoint

      • getMethod

        public String getMethod()
        Gets the name of HTTP method used to invoke this endpoint.
        Returns:
        the name of HTTP method used to invoke this endpoint

      • getPath

        public String getPath()
        Gets the path for this endpoint.
        Returns:
        the path for this endpoint

      • getDescription

        public String getDescription()
        Gets the description of this endpoint.
        Returns:
        the description of this endpoint

      • getBodyParam

        public RestParamData getBodyParam()
        Gets the body parameter of this endpoint.
        Returns:
        the body parameter of this endpoint

      • getPathParams

        public List<RestParamData> getPathParams()
        Gets the list of path parameters of this endpoint.
        Returns:
        the list of path parameters of this endpoint

      • getRequiredParams

        public List<RestParamData> getRequiredParams()
        Gets the list of required parameters of this endpoint.
        Returns:
        the list of required parameters of this endpoint

      • getOptionalParams

        public List<RestParamData> getOptionalParams()
        Gets the list of optional parameters of this endpoint.
        Returns:
        list of optional parameters of this endpoint

      • getFormats

        public List<RestFormatData> getFormats()
        Gets the list of formats returned by this endpoint.
        Returns:
        the list of formats returned by this endpoint

      • getStatuses

        public List<StatusData> getStatuses()
        Gets the list of HTTP responses returned by this endpoint.
        Returns:
        the list of HTTP responses returned by this endpoint

      • getNotes

        public List<String> getNotes()
        Gets list of notes (i.e. extra information) of this endpoint.
        Returns:
        the list of notes (i.e. extra information) of this endpoint

      • getForm

        public RestFormData getForm()
        Gets the form for testing this endpoint in the documentation page.
        Returns:
        the form for testing this endpoint in the documentation page

      • compareTo

        public int compareTo​(RestEndpointData otherEndpoint)
        Compares two RestEndpointData by their names so that the list of endpoints can be sorted.
        Specified by:
        compareTo in interface Comparable<RestEndpointData>
        Parameters:
        otherEndpoint - the other endpoint object to compare to
        Returns:
        a negative integer, zero, or a positive integer as the name of the supplied endpoint is greater than, equal to, or less than this endpoint, ignoring case considerations.

      • getReturnTypeSchema

        public String getReturnTypeSchema()
        Returns:
        the XML schema for this endpoint's return type

      • getEscapedReturnTypeSchema

        public String getEscapedReturnTypeSchema()