src/jalview/rest/RestHandler.java

   1 /*
   2  * Jalview - A Sequence Alignment Editor and Viewer ($$Version-Rel$$)
   3  * Copyright (C) $$Year-Rel$$ The Jalview Authors
   4  *
   5  * This file is part of Jalview.
   6  *
   7  * Jalview is free software: you can redistribute it and/or
   8  * modify it under the terms of the GNU General Public License
   9  * as published by the Free Software Foundation, either version 3
  10  * of the License, or (at your option) any later version.
  11  *
  12  * Jalview is distributed in the hope that it will be useful, but
  13  * WITHOUT ANY WARRANTY; without even the implied warranty
  14  * of MERCHANTABILITY or FITNESS FOR A PARTICULAR
  15  * PURPOSE.  See the GNU General Public License for more details.
  16  *
  17  * You should have received a copy of the GNU General Public License
  18  * along with Jalview.  If not, see <http://www.gnu.org/licenses/>.
  19  * The Jalview Authors are detailed in the 'AUTHORS' file.
  20  */
  21 package jalview.rest;
  22
  23 import java.io.BufferedReader;
  24 import java.io.IOException;
  25 import java.io.InputStreamReader;
  26 import java.io.PrintWriter;
  27 import java.lang.reflect.InvocationTargetException;
  28 import java.net.BindException;
  29 import java.util.HashMap;
  30 import java.util.Map;
  31
  32 import javax.servlet.ServletInputStream;
  33 import javax.servlet.http.HttpServletRequest;
  34 import javax.servlet.http.HttpServletResponse;
  35
  36 import org.eclipse.jetty.server.handler.ContextHandler;
  37
  38 import jalview.bin.Console;
  39 import jalview.httpserver.AbstractRequestHandler;
  40 import jalview.httpserver.HttpServer;
  41
  42 /**
  43  * A simple handler to process (or delegate) HTTP requests on /jalview/rest
  44  */
  45 public class RestHandler extends AbstractRequestHandler
  46 {
  47
  48   public enum Status
  49   {
  50     STARTED, IN_PROGRESS, FINISHED, ERROR, NOT_RUN
  51   }
  52
  53   public interface EndpointI
  54   {
  55     public String getPath();
  56
  57     public String getName();
  58
  59     public String getParameters();
  60
  61     public String getDescription();
  62
  63     public void processEndpoint(HttpServletRequest request,
  64             HttpServletResponse response);
  65
  66   }
  67
  68   private static final String MY_PATH = "rest";
  69
  70   private static final String MY_NAME = "Rest";
  71
  72   private String missingEndpointMessage = null;
  73
  74   private boolean init = false;
  75
  76   // map of method names and method handlers
  77   private Map<String, AbstractEndpoint> endpoints = null;
  78
  79   protected Map<String, AbstractEndpoint> getEndpoints()
  80   {
  81     return endpoints;
  82   }
  83
  84   protected AbstractEndpoint getNewEndpoint(String name)
  85   {
  86     if (getEndpoints() == null)
  87     {
  88       return null;
  89     }
  90     try
  91     {
  92       return getEndpoints().get(name).getClass()
  93               .getDeclaredConstructor(API.class).newInstance(this);
  94     } catch (InstantiationException | IllegalAccessException
  95             | IllegalArgumentException | InvocationTargetException
  96             | NoSuchMethodException | SecurityException e)
  97     {
  98       Console.debug("Could not instantiate new endpoint '" + name + "'", e);
  99     }
 100     return null;
 101   }
 102
 103   /**
 104    * Singleton instance of this class
 105    */
 106   private static RestHandler instance = null;
 107
 108   /**
 109    * Returns the singleton instance of this class
 110    *
 111    * @return
 112    * @throws BindException
 113    */
 114   public static RestHandler getInstance() throws BindException
 115   {
 116     synchronized (RestHandler.class)
 117     {
 118       if (instance == null)
 119       {
 120         instance = new RestHandler();
 121       }
 122     }
 123     return instance;
 124   }
 125
 126   /**
 127    * Private constructor enforces use of singleton
 128    *
 129    * @throws BindException
 130    */
 131   protected RestHandler() throws BindException
 132   {
 133     init();
 134
 135     /*
 136      * We don't register the handler here - this is done as a special case in
 137      * HttpServer initialisation; to do it here would invite an infinite loop of
 138      * RestHandler/HttpServer constructor
 139      */
 140   }
 141
 142   /**
 143    * Handle a jalview/rest request
 144    *
 145    * @throws IOException
 146    */
 147   @Override
 148   protected void processRequest(HttpServletRequest request,
 149           HttpServletResponse response) throws IOException
 150   {
 151     /*
 152      * Currently just echoes the request; add helper classes as required to
 153      * process requests
 154      */
 155     // This "pointless" call to request.getInputStream() seems to preserve the
 156     // InputStream for use later in getRequestBody.
 157     request.getInputStream();
 158
 159     String remoteAddr = request.getRemoteAddr();
 160     if (!("127.0.0.1".equals(remoteAddr) || "localhost".equals(remoteAddr)))
 161     {
 162       returnError(request, response, "Not authorised: " + remoteAddr,
 163               HttpServletResponse.SC_UNAUTHORIZED);
 164       return;
 165     }
 166     if (getEndpoints() == null)
 167     {
 168       final String queryString = request.getQueryString();
 169       final String reply = "REST not yet implemented; received "
 170               + request.getMethod() + ": " + request.getRequestURL()
 171               + (queryString == null ? "" : "?" + queryString);
 172       Console.error(reply);
 173
 174       response.setHeader("Cache-Control", "no-cache/no-store");
 175       response.setHeader("Content-type", "text/plain");
 176       final PrintWriter writer = response.getWriter();
 177       writer.write(reply);
 178       return;
 179     }
 180
 181     String endpointName = getRequestedEndpointName(request);
 182
 183     if (!getEndpoints().containsKey(endpointName)
 184             || getEndpoints().get(endpointName) == null)
 185     {
 186
 187       response.setHeader("Cache-Control", "no-cache/no-store");
 188       response.setHeader("Content-type", "text/plain");
 189       PrintWriter writer = response.getWriter();
 190       writer.write(missingEndpointMessage == null
 191               ? "REST endpoint '" + endpointName + "' not defined"
 192               : missingEndpointMessage);
 193       writer.write("\n");
 194       writer.write("Available endpoints are:\n");
 195       ContextHandler ch = HttpServer.getInstance().getContextHandler(this);
 196       String base = HttpServer.getInstance().getUri().toString();
 197       String contextPath = ch == null ? "" : ch.getContextPath();
 198       for (String key : getEndpoints().keySet())
 199       {
 200         writer.write(base + contextPath + "/" + key + "\n");
 201       }
 202       response.setStatus(HttpServletResponse.SC_BAD_REQUEST);
 203       return;
 204     }
 205
 206     response.setHeader("Cache-Control", "no-cache/no-store");
 207     response.setHeader("Content-type", "text/plain");
 208     EndpointI ep = getNewEndpoint(endpointName);
 209     ep.processEndpoint(request, response);
 210
 211     return;
 212   }
 213
 214   /**
 215    * Returns a display name for this service
 216    */
 217   @Override
 218   public String getName()
 219   {
 220     return MY_NAME;
 221   }
 222
 223   /**
 224    * Initialise methods
 225    *
 226    * @throws BindException
 227    */
 228   protected void init() throws BindException
 229   {
 230     init(MY_PATH);
 231   }
 232
 233   protected void init(String path) throws BindException
 234   {
 235     setPath(path);
 236     // Override this in extended class
 237     // e.g. registerHandler and addEndpoints
 238   }
 239
 240   protected void addEndpoint(AbstractEndpoint ep)
 241   {
 242     if (getEndpoints() == null)
 243     {
 244       endpoints = new HashMap<>();
 245     }
 246     endpoints.put(ep.getPath(), ep);
 247     Console.debug("REST API, added endpoint '" + ep.getPath() + "'");
 248   }
 249
 250   protected String getRequestedEndpointName(HttpServletRequest request)
 251   {
 252     String pathInfo = request.getPathInfo();
 253     int slashpos = pathInfo.indexOf('/', 1);
 254     return slashpos > 1 ? pathInfo.substring(1, slashpos)
 255             : pathInfo.substring(1);
 256   }
 257
 258   protected void returnError(HttpServletRequest request,
 259           HttpServletResponse response, String message)
 260   {
 261     returnError(request, response, message,
 262             HttpServletResponse.SC_INTERNAL_SERVER_ERROR);
 263   }
 264
 265   protected void returnError(HttpServletRequest request,
 266           HttpServletResponse response, String message, int statusCode)
 267   {
 268     response.setStatus(statusCode);
 269     String endpointName = getRequestedEndpointName(request);
 270     Console.error(getName() + " error: endpoint " + endpointName
 271             + " failed: '" + message + "'");
 272     try
 273     {
 274       PrintWriter writer = response.getWriter();
 275       writer.write("Endpoint " + endpointName + ": " + message);
 276     } catch (IOException e)
 277     {
 278       Console.debug("Could not write to REST response for endpoint "
 279               + endpointName, e);
 280     }
 281   }
 282
 283   protected void returnStatus(HttpServletResponse response, String id,
 284           Status status)
 285   {
 286     try
 287     {
 288       PrintWriter writer = response.getWriter();
 289       if (id != null)
 290         writer.write("id=" + id + "\n");
 291       if (status != null)
 292         writer.write("status=" + status.toString() + "\n");
 293     } catch (IOException e)
 294     {
 295       Console.debug("Could not write status to REST response for id:" + id,
 296               e);
 297     }
 298   }
 299
 300   protected String getRequestBody(HttpServletRequest request,
 301           HttpServletResponse response) throws IOException
 302   {
 303     StringBuilder sb = new StringBuilder();
 304     BufferedReader reader = null;
 305     Console.debug("REQUEST=" + request.toString());
 306     Console.debug("REQUEST.Content-Length=" + request.getContentLength());
 307     try
 308     {
 309       reader = request.getReader();
 310       Console.debug("Using getReader()");
 311     } catch (IllegalStateException e)
 312     {
 313       ServletInputStream is = request.getInputStream();
 314       reader = new BufferedReader(new InputStreamReader(is));
 315       Console.debug("Using getInputStream()");
 316     }
 317     if (reader != null)
 318     {
 319       try
 320       {
 321         String line;
 322         while ((line = reader.readLine()) != null)
 323         {
 324           sb.append(line).append('\n');
 325         }
 326       } finally
 327       {
 328         reader.close();
 329       }
 330     }
 331     else
 332     {
 333       returnError(request, response, "Error reading body of HTTP request");
 334     }
 335     return sb.toString();
 336   }
 337 }