/*
    * Licensed to The Apereo Foundation under one or more contributor license
    * agreements. See the NOTICE file distributed with this work for additional
    * information regarding copyright ownership.
    *
    *
    * The Apereo Foundation licenses this file to you under the Educational
    * Community License, Version 2.0 (the "License"); you may not use this file
    * except in compliance with the License. You may obtain a copy of the License
   * at:
   *
   *   http://opensource.org/licenses/ecl2.txt
   *
   * Unless required by applicable law or agreed to in writing, software
   * distributed under the License is distributed on an "AS IS" BASIS, WITHOUT
   * WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.  See the
   * License for the specific language governing permissions and limitations under
   * the License.
   *
   */
  
  package org.opencastproject.runtimeinfo.rest;
  
  import static org.apache.commons.lang3.StringUtils.isBlank;
  
  import org.opencastproject.util.JaxbXmlSchemaGenerator;
  import org.opencastproject.util.doc.DocData;
  import org.opencastproject.util.doc.rest.RestParameter;
  import org.opencastproject.util.doc.rest.RestResponse;
  
  import org.apache.commons.lang3.StringEscapeUtils;
  
  import java.util.ArrayList;
  import java.util.List;
  import java.util.Vector;
  
  public class RestEndpointData implements Comparable<RestEndpointData> {
  
    /**
     * The name of the endpoint, which should be unique. In the documentation page, the same type of endpoints are shown
     * in ascending order of name.
     */
    private String name;
  
    /**
     * The HTTP method used to invoke the endpoint.
     */
    private String httpMethod;
  
    /**
     * The path for this endpoint (e.g. /search OR /add/{id}).
     */
    private String path;
  
    /**
     * The description of this endpoint.
     */
    private String description;
  
    /**
     * The body parameter of this endpoint.
     */
    private RestParamData bodyParam;
  
    /**
     * The list of path parameters of this endpoint.
     */
    private List<RestParamData> pathParams;
  
    /**
     * The list of required query parameters of this endpoint.
     */
    private List<RestParamData> requiredParams;
  
    /**
     * The list of optional query parameters of this endpoint.
     */
    private List<RestParamData> optionalParams;
  
    /**
     * The list of notes (i.e. extra information) of this endpoint.
     */
    private List<String> notes;
  
    /**
     * The list of formats returned by this endpoint.
     */
    private List<RestFormatData> formats;
  
    /**
     * The list of HTTP responses returned by this endpoint.
     */
    private List<StatusData> statuses;
  
    /**
     * The form for testing this endpoint in the documentation page.
     */
    private RestFormData form;
  
   /** The XML schema for data returned by this endpoint. */
   private String returnTypeSchema = null;
 
   /**
    * Create a new basic endpoint, you should use the add methods to fill in the rest of the information about the
    * endpoint data
    *
    * @param returnType
    *          the endpoint's return type
    * @param name
    *          the endpoint's name (this should be unique in the same type of endpoints)
    * @param httpMethod
    *          the HTTP method used for this endpoint
    * @param path
    *          the path for this endpoint (e.g. /search OR /add/{id})
    * @param description
    *          [optional] the description of this endpoint
    * @throws IllegalArgumentException
    *           if name is null, name is not alphanumeric, method is null, path is null or path is not valid.
    */
   public RestEndpointData(Class<?> returnType, String name, String httpMethod, String path, String description)
           throws IllegalArgumentException {
     if (!DocData.isValidName(name)) {
       throw new IllegalArgumentException("Name must not be null and must be alphanumeric.");
     }
     if ((httpMethod == null) || (httpMethod.isEmpty())) {
       throw new IllegalArgumentException("Method must not be null and must not be empty.");
     }
     if (!RestDocData.isValidPath(path)) {
       throw new IllegalArgumentException(String.format("Path '%s' must not be null and must look something like "
               + "/a/b/{c}.", path));
     }
     this.returnTypeSchema = JaxbXmlSchemaGenerator.getXmlSchema(returnType);
     this.name = name;
     this.httpMethod = httpMethod.toUpperCase();
     this.path = path;
     this.description = description;
   }
 
   /**
    * Returns a string representation of this object.
    *
    * @return a string representation of this object
    */
   @Override
   public String toString() {
     return "ENDP:" + name + ":" + httpMethod + " " + path + " :body=" + bodyParam + " :req=" + requiredParams
             + " :opt=" + optionalParams + " :formats=" + formats + " :status=" + statuses + " :form=" + form;
   }
 
   /**
    * Adds a body parameter to this endpoint. Once added, the body parameter becomes a required parameter.
    *
    * @param restParam
    *          a RestParameter annotation object corresponding to the body parameter
    *
    * @return the new RestParamData object in case you want to set attributes
    */
   public RestParamData addBodyParam(RestParameter restParam) {
     RestParamData.Type type = RestParamData.Type.valueOf(restParam.type().name());
     RestParamData param = new RestParamData("BODY", type, restParam.defaultValue(),
             restParam.description(), null);
     param.setRequired(true);
     bodyParam = param;
     return param;
   }
 
   /**
    * Adds a path parameter for this endpoint, this would be a parameter which is passed as part of the path (e.g.
    * /my/path/{param}) and thus must use a name which is safe to be placed in a URL and does not contain a slash (/)
    *
    * @param param
    *          the path parameter to add
    * @throws IllegalStateException
    *           if the type of the path parameter is FILE or TEXT
    */
   public void addPathParam(RestParamData param) throws IllegalStateException {
     if (RestParamData.Type.FILE.name().equals(param.getType())
             || RestParamData.Type.TEXT.name().equals(param.getType())) {
       throw new IllegalStateException("Cannot add path param of type FILE or TEXT.");
     }
     param.setRequired(true);
     param.setPath(true);
     if (pathParams == null) {
       pathParams = new Vector<RestParamData>(3);
     }
     pathParams.add(param);
   }
 
   /**
    * Adds a required form parameter for this endpoint, this would be a parameter which is passed encoded as part of the
    * request body (commonly referred to as a post or form parameter). <br>
    * WARNING: This should generally be reserved for endpoints which are used for processing, it is better to use path
    * params unless the required parameter is not part of an identifier for the resource.
    *
    * @param param
    *          the required parameter to add
    */
   public void addRequiredParam(RestParamData param) throws IllegalStateException {
     param.setRequired(true);
     param.setPath(false);
     if (requiredParams == null) {
       requiredParams = new Vector<RestParamData>(3);
     }
     requiredParams.add(param);
   }
 
   /**
    * Adds an optional parameter for this endpoint, this would be a parameter which is passed in the query string (for
    * GET) or encoded as part of the body otherwise (often referred to as a post or form parameter).
    *
    * @param param
    *          the optional parameter to add
    */
   public void addOptionalParam(RestParamData param) {
     param.setRequired(false);
     param.setPath(false);
     if (optionalParams == null) {
       optionalParams = new Vector<RestParamData>(3);
     }
     optionalParams.add(param);
   }
 
   /**
    * Adds a format for the return data for this endpoint.
    *
    * @param format
    *          a RestFormatData object
    */
   public void addFormat(RestFormatData format) {
     if (formats == null) {
       formats = new Vector<RestFormatData>(2);
     }
     formats.add(format);
   }
 
   /**
    * Adds a response status for this endpoint.
    *
    * @param restResponse
    *          a RestResponse object containing the HTTP response code and description
    */
   public void addStatus(RestResponse restResponse) {
     if (statuses == null) {
       statuses = new Vector<StatusData>(3);
     }
     statuses.add(new StatusData(restResponse));
   }
 
   /**
    * Adds a note for this endpoint.
    *
    * @param note
    *          a string providing more information about this endpoint
    * @throws IllegalArgumentException
    *           if note is blank (e.g. null, empty string)
    */
   public void addNote(String note) throws IllegalArgumentException {
     if (isBlank(note)) {
       throw new IllegalArgumentException("Note must not be null or blank.");
     }
     if (notes == null) {
       notes = new Vector<String>(3);
     }
     notes.add(note);
   }
 
   /**
    * Sets the test form for this endpoint, if this is null then no test form is rendered for this endpoint.
    *
    * @param form
    *          the test form object (null to clear the form)
    */
   public void setTestForm(RestFormData form) {
     this.form = form;
   }
 
   /**
    * Returns whether this endpoint's HTTP method is GET
    *
    * @return true if this endpoint method is GET, otherwise false
    */
   public boolean isGetMethod() {
     return "GET".equals(httpMethod);
   }
 
   /**
    * Returns the URL-encoded query string for a GET endpoint.
    *
    * @return the calculated query string for a GET endpoint (e.g. ?blah=1), will be urlencoded for html display
    */
   public String getQueryString() {
     String qs = "";
     if (isGetMethod()) {
       if (optionalParams != null && !optionalParams.isEmpty()) {
         StringBuilder sb = new StringBuilder();
         sb.append("?");
         for (RestParamData p : optionalParams) {
           if (sb.length() > 2) {
             sb.append("&");
           }
           sb.append(p.getName());
           sb.append("=");
           if (p.getDefaultValue() != null) {
             sb.append(p.getDefaultValue());
           } else {
             sb.append("{");
             sb.append(p.getName());
             sb.append("}");
           }
         }
         qs = StringEscapeUtils.escapeHtml4(sb.toString());
       }
     }
     return qs;
   }
 
   /**
    * Gets the name of this endpoint.
    *
    * @return the name of this endpoint
    */
   public String getName() {
     return name;
   }
 
   /**
    * Gets the name of HTTP method used to invoke this endpoint.
    *
    * @return the name of HTTP method used to invoke this endpoint
    */
   public String getMethod() {
     return httpMethod;
   }
 
   /**
    * Gets the path for this endpoint.
    *
    * @return the path for this endpoint
    */
   public String getPath() {
     return path;
   }
 
   /**
    * Gets the description of this endpoint.
    *
    * @return the description of this endpoint
    */
   public String getDescription() {
     return description;
   }
 
   /**
    * Gets the body parameter of this endpoint.
    *
    * @return the body parameter of this endpoint
    */
   public RestParamData getBodyParam() {
     return bodyParam;
   }
 
   /**
    * Gets the list of path parameters of this endpoint.
    *
    * @return the list of path parameters of this endpoint
    */
   public List<RestParamData> getPathParams() {
     if (pathParams == null) {
       pathParams = new ArrayList<RestParamData>(0);
     }
     return pathParams;
   }
 
   /**
    * Gets the list of required parameters of this endpoint.
    *
    * @return the list of required parameters of this endpoint
    */
   public List<RestParamData> getRequiredParams() {
     if (requiredParams == null) {
       requiredParams = new ArrayList<RestParamData>(0);
     }
     return requiredParams;
   }
 
   /**
    * Gets the list of optional parameters of this endpoint.
    *
    * @return list of optional parameters of this endpoint
    */
   public List<RestParamData> getOptionalParams() {
     if (optionalParams == null) {
       optionalParams = new ArrayList<RestParamData>(0);
     }
     return optionalParams;
   }
 
   /**
    * Gets the list of formats returned by this endpoint.
    *
    * @return the list of formats returned by this endpoint
    */
   public List<RestFormatData> getFormats() {
     if (formats == null) {
       formats = new ArrayList<RestFormatData>(0);
     }
     return formats;
   }
 
   /**
    * Gets the list of HTTP responses returned by this endpoint.
    *
    * @return the list of HTTP responses returned by this endpoint
    */
   public List<StatusData> getStatuses() {
     if (statuses == null) {
       statuses = new ArrayList<StatusData>(0);
     }
     return statuses;
   }
 
   /**
    * Gets list of notes (i.e. extra information) of this endpoint.
    *
    * @return the list of notes (i.e. extra information) of this endpoint
    */
   public List<String> getNotes() {
     if (notes == null) {
       notes = new ArrayList<>(0);
     }
     return notes;
   }
 
   /**
    * Gets the form for testing this endpoint in the documentation page.
    *
    * @return the form for testing this endpoint in the documentation page
    */
   public RestFormData getForm() {
     return form;
   }
 
   /**
    * Compares two RestEndpointData by their names so that the list of endpoints can be sorted.
    *
    * @param otherEndpoint
    *          the other endpoint object to compare to
    *
    * @return a negative integer, zero, or a positive integer as the name of the supplied endpoint is greater than, equal
    *         to, or less than this endpoint, ignoring case considerations.
    */
   @Override
   public int compareTo(RestEndpointData otherEndpoint) {
     return name.compareToIgnoreCase(otherEndpoint.name);
   }
 
   /**
    * @return the XML schema for this endpoint's return type
    */
   public String getReturnTypeSchema() {
     return returnTypeSchema;
   }
 
   public String getEscapedReturnTypeSchema() {
     return StringEscapeUtils.escapeXml(returnTypeSchema);
   }
 
 }