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}