001package jmri.spi;
002
003import com.fasterxml.jackson.databind.ObjectMapper;
004import javax.annotation.Nonnull;
005
006import jmri.server.json.JsonConnection;
007import jmri.server.json.JsonHttpService;
008import jmri.server.json.JsonSocketService;
009
010/**
011 * Factory interface for JSON services.
012 * <p>
013 * A JSON service is a service provided by the
014 * {@link jmri.server.json.JsonServer}. This API allows JSON services to be
015 * defined in a modular manner. The factory pattern is used since each
016 * connection gets a unique instance of each service.
017 *
018 * @param <H> the specific supported HTTP service
019 * @param <S> the specific supported (Web)Socket service
020 * @author Randall Wood Copyright 2016, 2018
021 */
022public interface JsonServiceFactory<H extends JsonHttpService, S extends JsonSocketService<H>> extends JmriServiceProviderInterface {
023
024    /**
025     * Get the service type(s) for services created by this factory respond to.
026     * These type must have valid schemas for messages received from a client
027     * and sent to a client.
028     * <p>
029     * Types should be single words, in camelCase if needed, unless supporting a
030     * plural noun introduced in the JSON 1.x or 2.x protocols and exposed in
031     * the JSON 3.0 or newer protocol.
032     * <p>
033     * If a service returns no types, it will never be used.
034     *
035     * @param version The JSON protocol version major component identifier
036     * @return An array of types this service responds to
037     */
038    @Nonnull
039    String[] getTypes(@Nonnull String version);
040
041    /**
042     * Get the message type(s) services created by this factory send, if not
043     * also listed in {@link #getTypes(String)}. These types must only have
044     * schemas for messages sent to a client.
045     * <p>
046     * Types should be single words, in camelCase if needed, unless supporting a
047     * plural noun introduced in the JSON 1.x or 2.x protocols and exposed in
048     * the JSON 3.0 or newer protocol.
049     *
050     * @param version The JSON protocol version major component identifier
051     * @return An array of types this service sends, but does not respond to
052     */
053    @Nonnull
054    default String[] getSentTypes(@Nonnull String version) {
055        return new String[0];
056    }
057
058    /**
059     * Get the message type(s) services created by this factory receive, if not
060     * also listed in {@link #getTypes(String)}. These types must only have
061     * schemas for messages received from a client.
062     * <p>
063     * Types should be single words, in camelCase if needed, unless supporting a
064     * plural noun introduced in the JSON 1.x or 2.x protocols and exposed in
065     * the JSON 3.0 or newer protocol.
066     *
067     * @param version The JSON protocol version major component identifier
068     * @return An array of types this service sends, but does not respond to
069     */
070    @Nonnull
071    default String[] getReceivedTypes(@Nonnull String version) {
072        return new String[0];
073    }
074
075    /**
076     * Create a JSON service for the given connection. This connection can be a
077     * WebSocket or raw socket.
078     *
079     * @param connection The connection for this service to respond to
080     * @param version The JSON protocol version major component identifier
081     * @return A service or null if the service does not support sockets
082     */
083    @Nonnull
084    S getSocketService(@Nonnull JsonConnection connection, @Nonnull String version);
085
086    /**
087     * Create a JSON HTTP service.
088     *
089     * @param mapper  The object mapper for the HTTP service to use
090     * @param version The JSON protocol version major component identifier
091     * @return A servlet or null if the service does not support HTTP
092     */
093    @Nonnull
094    H getHttpService(@Nonnull ObjectMapper mapper, @Nonnull String version);
095
096}