Class JsonHttpService

    • Constructor Detail

      • JsonHttpService

        protected JsonHttpService​(@Nonnull
                                  ObjectMapper mapper)
        Create an HTTP handler for a JSON service.
        Parameters:
        mapper - the ObjectMapper to create new JSON nodes
    • Method Detail

      • doGet

        @Nonnull
        public abstract JsonNode doGet​(@Nonnull
                                       java.lang.String type,
                                       @Nonnull
                                       java.lang.String name,
                                       @Nonnull
                                       JsonNode data,
                                       @Nonnull
                                       JsonRequest request)
                                throws JsonException
        Respond to an HTTP GET request for the requested name.

        If name is null, return a list of all objects for the given type, if appropriate.

        This method should throw a 500 Internal Server Error if type is not recognized.

        Parameters:
        type - the type of the requested object
        name - the system name of the requested object
        data - JSON data set of attributes of the requested object
        request - the JSON request
        Returns:
        a JSON description of the requested object
        Throws:
        JsonException - if the named object does not exist or other error occurs
      • doPost

        @Nonnull
        public abstract JsonNode doPost​(@Nonnull
                                        java.lang.String type,
                                        @Nonnull
                                        java.lang.String name,
                                        @Nonnull
                                        JsonNode data,
                                        @Nonnull
                                        JsonRequest request)
                                 throws JsonException
        Respond to an HTTP POST request for the requested name.

        This method should throw a 400 Invalid Request error if the named object does not exist.

        Parameters:
        type - the type of the requested object
        name - the system name of the requested object
        data - JSON data set of attributes of the requested object to be updated
        request - the JSON request
        Returns:
        a JSON description of the requested object after updates have been applied
        Throws:
        JsonException - if the named object does not exist or other error occurs
      • doPut

        @Nonnull
        public JsonNode doPut​(@Nonnull
                              java.lang.String type,
                              @Nonnull
                              java.lang.String name,
                              @Nonnull
                              JsonNode data,
                              @Nonnull
                              JsonRequest request)
                       throws JsonException
        Respond to an HTTP PUT request for the requested name.

        Throw an HTTP 405 Method Not Allowed exception if new objects of the type are not intended to be addable.

        Parameters:
        type - the type of the requested object
        name - the system name of the requested object
        data - JSON data set of attributes of the requested object to be created or updated
        request - the JSON request
        Returns:
        a JSON description of the requested object
        Throws:
        JsonException - if the method is not allowed or other error occurs
      • doDelete

        public void doDelete​(@Nonnull
                             java.lang.String type,
                             @Nonnull
                             java.lang.String name,
                             @Nonnull
                             JsonNode data,
                             @Nonnull
                             JsonRequest request)
                      throws JsonException
        Respond to an HTTP DELETE request for the requested name.

        Throw an HTTP 405 Method Not Allowed exception if the object is not intended to be removable.

        Do not throw an error if the requested object does not exist.

        Parameters:
        type - the type of the deleted object
        name - the system name of the deleted object
        data - additional data
        request - the JSON request
        Throws:
        JsonException - if this method is not allowed or other error occurs
      • doGetList

        @Nonnull
        public abstract JsonNode doGetList​(@Nonnull
                                           java.lang.String type,
                                           @Nonnull
                                           JsonNode data,
                                           @Nonnull
                                           JsonRequest request)
                                    throws JsonException
        Respond to an HTTP GET request for a list of items of type.

        This is called by the JsonServlet to handle get requests for a type, but no name. Services that do not have named objects, such as the JsonTimeHttpService should respond to this with a list containing a single JSON object. Services that can't return a list may throw a 400 Bad Request JsonException in this case.

        Parameters:
        type - the type of the requested list
        data - JSON data set of attributes of the requested objects
        request - the JSON request
        Returns:
        a JSON list or message containing type "list", the list as data, and the passed in id
        Throws:
        JsonException - may be thrown by concrete implementations
      • doSchema

        @Nonnull
        public abstract JsonNode doSchema​(@Nonnull
                                          java.lang.String type,
                                          boolean server,
                                          @Nonnull
                                          JsonRequest request)
                                   throws JsonException
        Get the JSON Schema for the data property of the requested type of JSON object. It is a invalid for implementations to not return a valid schema that clients can use to validate a request to or response from the JSON services.

        Note that a schema must be contained in a standard object as:

        {"type":"schema", "data":{"schema":<em>schema</em>, "server":boolean}}

        If using doSchema(String, boolean, String, String, int), an implementation can be as simple as: return doSchema(type, server, "path/to/client/schema.json", "path/to/server/schema.json", id);

        Parameters:
        type - the type for which a schema is requested
        server - true if the schema is for a message from the server; false if the schema is for a message from the client
        request - the JSON request
        Returns:
        a JSON Schema valid for the type
        Throws:
        JsonException - if an error occurs preparing schema; if type is is not a type handled by this service, this must be thrown with an error code of 500 and the localized message ERROR_UNKNOWN_TYPE
      • doSchema

        @Nonnull
        protected final JsonNode doSchema​(@Nonnull
                                          java.lang.String type,
                                          boolean server,
                                          @Nonnull
                                          java.lang.String serverSchema,
                                          @Nonnull
                                          java.lang.String clientSchema,
                                          int id)
                                   throws JsonException
        Helper to make implementing doSchema(String, boolean, JsonRequest) easier. Throws a JsonException based on an IOException or NullPointerException if unable to read the schemas as resources.
        Parameters:
        type - the type for which a schema is requested
        server - true if the schema is for a message from the server; false if the schema is for a message from the client
        serverSchema - the path to the schema for a response object of type
        clientSchema - the path to the schema for a request object of type
        id - the message id set by the client
        Returns:
        a JSON Schema valid for the type
        Throws:
        JsonException - if an error occurs preparing schema
      • doSchema

        @Nonnull
        protected final JsonNode doSchema​(@Nonnull
                                          java.lang.String type,
                                          boolean server,
                                          @Nonnull
                                          JsonNode schema,
                                          int id)
        Helper to make implementing doSchema(String, boolean, JsonRequest) easier.
        Parameters:
        type - the type for which a schema is requested
        server - true if the schema is for a message from the server; false if the schema is for a message from the client
        schema - the schema for a response object of type
        id - the message id set by the client
        Returns:
        a JSON Schema valid for the type
      • acceptForceDeleteToken

        public final boolean acceptForceDeleteToken​(@Nonnull
                                                    java.lang.String type,
                                                    @Nonnull
                                                    java.lang.String name,
                                                    @CheckForNull
                                                    java.lang.String token)
        Verify a deletion token. If the token is not valid any pending deletion tokens for the type and name are also deleted.
        Parameters:
        type - the type of object pending deletion
        name - the name of object pending deletion
        token - the token previously provided to client
        Returns:
        true if token was provided to client and no other delete attempt was made by client with a different or missing token since token was issued to client; false otherwise
      • throwDeleteConflictException

        public final void throwDeleteConflictException​(@Nonnull
                                                       java.lang.String type,
                                                       @Nonnull
                                                       java.lang.String name,
                                                       @Nonnull
                                                       ArrayNode conflicts,
                                                       @Nonnull
                                                       JsonRequest request)
                                                throws JsonException
        Throw an HTTP CONFLICT (409) exception when an object is requested to be deleted and it is in use. This exception will include a token that can be used to force deletion by the client and may include a JSON list of the objects using the object for which deletion was requested.
        Parameters:
        type - the type of object in conflicting state
        name - the name of the object in conflicting state
        conflicts - the using objects of this object; may be empty
        request - the JSON request
        Throws:
        JsonException - the exception