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