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}