001package com.nimbusds.common.jsonrpc2;
002
003
004import java.io.IOException;
005import java.io.PrintWriter;
006import java.util.Arrays;
007
008import javax.servlet.http.HttpServletResponse;
009
010
011/**
012 * Welcome banner for Connect2id JSON-RPC 2.0 services.
013 *
014 * <p>Example output:
015 *
016 * <pre>
017 * Use HTTP POST to submit your JSON-RPC 2.0 request
018 *
019 * Web service: LdapAuth, version 3.0.1 (2014-02-20)
020 * Vendor: Connect2id Ltd., http://connect2id.com
021 * 
022 * Supported JSON-RPC 2.0 requests:
023 *      * user.auth
024 *      * user.get
025 *      * ws.getName
026 *      * ws.getTime
027 *      * ws.getVersion
028 * </pre>
029 */
030public class Banner {
031
032
033        /**
034         * The web service name.
035         */
036        private String wsName;
037        
038        
039        /**
040         * The web service version and build date.
041         */
042        private String wsVersion;
043        
044        
045        /**
046         * The handled methods, sorted.
047         */
048        private String[] handledMethods;
049        
050        
051        /**
052         * The composed banner message.
053         */
054        private String bannerMessage;
055        
056        
057        /**
058         * Creates a new welcome banner for a Connect2id JSON-RPC 2.0 service.
059         *
060         * @param wsName    The web service name. Must not be {@code null}.
061         * @param wsVersion The web service version and build date. Must not be
062         *                  {@code null}.
063         * @param methods   The handled methods. Must not be {@code null}.
064         */
065        public Banner(final String wsName,
066                      final String wsVersion,
067                      final String[] methods) {
068        
069                if (wsName == null)
070                        throw new IllegalArgumentException("The web service name must not be null");
071                
072                this.wsName = wsName;
073                
074                if (wsVersion == null)
075                        throw new IllegalArgumentException("The web service version must not be null");
076                
077                this.wsVersion = wsVersion;
078                
079                if (methods == null)
080                        throw new IllegalArgumentException("The handled JSON-RPC 2.0 method names must not be null");
081                
082                handledMethods = Arrays.copyOf(methods, methods.length);
083
084                // Sort in place
085                Arrays.sort(handledMethods);
086                
087                bannerMessage = composeMessage(wsName, wsVersion, handledMethods);
088        }
089        
090        
091        /**
092         * Gets the web service name.
093         *
094         * @return The web service name.
095         */
096        public String getWsName() {
097        
098                return wsName;
099        }
100        
101        
102        /**
103         * Gets the web service version and build date.
104         *
105         * @return The web service version and build date.
106         */
107        public String getWsVersion() {
108        
109                return wsVersion;
110        }
111        
112        
113        /**
114         * Gets the handled JSON-RPC 2.0 methods.
115         *
116         * @return The handled JSON-RPC 2.0 methods, sorted.
117         */
118        public String[] getHandledJSONRPC2Methods() {
119        
120                return handledMethods;
121        }
122        
123        
124        /**
125         * Composes a banner message.
126         *
127         * @param wsName    The web service name. Must not be {@code null}.
128         * @param wsVersion The web service version and build date. Must not be
129         *                  {@code null}.
130         * @param methods   The handled methods. Must not be {@code null}.
131         *
132         * @return The banner message.
133         */
134        public static String composeMessage(final String wsName, 
135                                            final String wsVersion,
136                                            final String[] methods) {
137        
138                StringBuilder sb = new StringBuilder();
139                
140                sb.append("Use HTTP POST to submit your JSON-RPC 2.0 request\n");
141                sb.append('\n');
142                sb.append("Web service: " + wsName + ", version " + wsVersion + '\n');
143                sb.append("Vendor: Connect2id Ltd., http://connect2id.com\n");
144                sb.append('\n');
145                sb.append("Supported JSON-RPC 2.0 requests:\n");
146
147                for (String m: methods) {
148                        sb.append("\t* ");
149                        sb.append(m);
150                        sb.append('\n');
151                }
152                
153                return sb.toString();
154        }
155
156
157        /**
158         * Applies this banner to the specified HTTP servlet response.
159         *
160         * <p>Appends a "X-Web-Service" HTTP header set to {@link #getWsName}.
161         *
162         * <p>Sets the "Content-Type" HTTP header to "text/plain;charset=utf-8".
163         *
164         * <p>Prints a message with the following format:
165         *
166         * <pre>
167         * Use HTTP POST to submit your JSON-RPC 2.0 request
168         *
169         * Web service: [ws-name], [ws-version]
170         * Vendor: Connect2id Ltd., http://connect2id.com
171         * 
172         * Supported JSON-RPC 2.0 requests:
173         *      * [method-1]
174         *      * [method-2]
175         *      * [method-x]
176         * </pre>
177         *
178         * @param httpResponse The HTTP servlet response.
179         *
180         * @throws IOException If an I/O exception was encountered.
181         */
182        public void apply(final HttpServletResponse httpResponse)
183                throws IOException {
184                
185                // Identify web service name in the HTTP header
186                httpResponse.setHeader("X-Web-Service", wsName);
187                
188                // Indicate a plain text message
189                httpResponse.setContentType("text/plain;charset=utf-8");
190                
191                PrintWriter out = httpResponse.getWriter();
192
193                // Identify web service and print message to use
194                // HTTP POST instead
195                out.println(bannerMessage);
196
197                out.close();
198        }
199}