001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.juneau.rest.server.widget;
018
019import static org.apache.juneau.commons.utils.Shorts.*;
020import static org.apache.juneau.commons.utils.ThrowableUtils.*;
021
022import java.io.*;
023
024import org.apache.juneau.commons.svl.*;
025import org.apache.juneau.http.response.*;
026import org.apache.juneau.marshall.cp.*;
027import org.apache.juneau.marshall.html.*;
028import org.apache.juneau.rest.server.*;
029
030/**
031 * Defines an interface for resolvers of <js>"${W:...}"</js> string variables.
032 *
033 * <p>
034 * Widgets must provide one of the following public constructors:
035 * <ul>
036 *    <li><code><jk>public</jk> Widget();</code>
037 *    <li><code><jk>public</jk> Widget(ContextProperties);</code>
038 * </ul>
039 *
040 * <p>
041 * Widgets can be defined as inner classes of REST resource classes.
042 *
043 * <h2 class='section'>See Also:</h2><ul>
044 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/HtmlPredefinedWidgets">Predefined Widgets</a>
045 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/HtmlWidgets">Widgets</a>
046 * </ul>
047 */
048public abstract class Widget implements HtmlWidget {
049
050   /**
051    * Resolves the HTML content for this widget.
052    *
053    * <p>
054    * A returned value of <jk>null</jk> will cause nothing to be added to the page.
055    *
056    * @param req The HTTP request object.
057    * @param res The current HTTP response.
058    * @return The HTML content of this widget.
059    */
060   public String getHtml(RestRequest req, RestResponse res) {
061      return null;
062   }
063
064   @Override /* Overridden from HtmlWidget */
065   public String getHtml(VarResolverSession session) {
066      return getHtml(req(session), res(session));
067   }
068
069   /**
070    * The widget key.
071    *
072    * <p>
073    * (i.e. The variable name inside the <js>"${W:...}"</js> variable).
074    *
075    * <p>
076    * The returned value must not be <jk>null</jk>.
077    *
078    * <p>
079    * If not overridden, the default value is the class simple name.
080    *
081    * @return The widget key.
082    */
083   @Override
084   public String getName() { return cns(this); }
085
086   /**
087    * Resolves any Javascript that should be added to the <xt>&lt;head&gt;/&lt;script&gt;</xt> element.
088    *
089    * <p>
090    * A returned value of <jk>null</jk> will cause nothing to be added to the page.
091    *
092    * @param req The HTTP request object.
093    * @param res The current HTTP response.
094    * @return The Javascript needed by this widget.
095    */
096   public String getScript(RestRequest req, RestResponse res) {
097      return null;
098   }
099
100   @Override /* Overridden from HtmlWidget */
101   public String getScript(VarResolverSession session) {
102      return getScript(req(session), res(session));
103   }
104
105   /**
106    * Resolves any CSS styles that should be added to the <xt>&lt;head&gt;/&lt;style&gt;</xt> element.
107    *
108    * <p>
109    * A returned value of <jk>null</jk> will cause nothing to be added to the page.
110    *
111    * @param req The HTTP request object.
112    * @param res The current HTTP response.
113    * @return The CSS styles needed by this widget.
114    */
115   public String getStyle(RestRequest req, RestResponse res) {
116      return null;
117   }
118
119   @Override /* Overridden from HtmlWidget */
120   public String getStyle(VarResolverSession session) {
121      return getStyle(req(session), res(session));
122   }
123
124   private static RestRequest req(VarResolverSession session) {
125      return session.getBean(RestRequest.class).orElseThrow(InternalServerError::new);
126   }
127
128   private static RestResponse res(VarResolverSession session) {
129      return session.getBean(RestResponse.class).orElseThrow(InternalServerError::new);
130   }
131
132   /**
133    * Returns the file finder to use for finding files on the file system.
134    *
135    * @param req The HTTP request object. Must not be <jk>null</jk>.
136    * @return The file finder to used for finding files on the file system.
137    */
138   protected FileFinder getFileFinder(RestRequest req) {
139      return req.getContext().getStaticFiles();
140   }
141
142   /**
143    * Loads the specified HTML file and strips HTML comments from the file.
144    *
145    * <p>
146    * Comment are assumed to be <js>"&lt;!-- --&gt;"</js> code blocks.
147    *
148    * @param req The HTTP request object. Must not be <jk>null</jk>.
149    * @param name Name of the desired resource.
150    * @return The resource converted to a string, or <jk>null</jk> if the resource could not be found.
151    */
152   protected String loadHtml(RestRequest req, String name) {
153      try {
154         return getFileFinder(req).getString(name, null).map(s -> s.replaceAll("(?s)<!--(.*?)-->\\s*", "")).orElse(null);
155      } catch (IOException e) {
156         throw toRex(e);
157      }
158   }
159
160   /**
161    * Same as {@link #loadHtml(RestRequest,String)} but replaces request-time SVL variables.
162    *
163    * <h4 class='section'>See Also:</h4><ul>
164    *    <li class='jm'>{@link RestContext#getVarResolver()}
165    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
166    * </ul>
167    *
168    * @param req The current HTTP request. Must not be <jk>null</jk>.
169    * @param res The current HTTP response.
170    * @param name Name of the desired resource.
171    * @return The resource converted to a string, or <jk>null</jk> if the resource could not be found.
172    * @throws IOException Thrown by underlying stream.
173    */
174   protected String loadHtmlWithVars(RestRequest req, RestResponse res, String name) throws IOException {
175      return req.getVarResolverSession().resolve(loadHtml(req, name));
176   }
177
178   /**
179    * Loads the specified javascript file and strips any Javascript comments from the file.
180    *
181    * <p>
182    * Comments are assumed to be Java-style block comments: <js>"/*"</js>.
183    *
184    * @param req The HTTP request object. Must not be <jk>null</jk>.
185    * @param name Name of the desired resource.
186    * @return The resource converted to a string, or <jk>null</jk> if the resource could not be found.
187    */
188   protected String loadScript(RestRequest req, String name) {
189      try {
190         return getFileFinder(req).getString(name, null).map(s -> s.replaceAll("(?s)\\/\\*(.*?)\\*\\/\\s*", "")).orElse(null);
191      } catch (IOException e) {
192         throw new UncheckedIOException(e);
193      }
194   }
195
196   /**
197    * Same as {@link #loadScript(RestRequest,String)} but replaces request-time SVL variables.
198    *
199    * <h4 class='section'>See Also:</h4><ul>
200    *    <li class='jm'>{@link RestContext#getVarResolver()}
201    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
202    * </ul>
203    *
204    * @param req The current HTTP request. Must not be <jk>null</jk>.
205    * @param res The current HTTP response.
206    * @param name Name of the desired resource.
207    * @return The resource converted to a string, or <jk>null</jk> if the resource could not be found.
208    * @throws IOException Thrown by underlying stream.
209    */
210   protected String loadScriptWithVars(RestRequest req, RestResponse res, String name) throws IOException {
211      return req.getVarResolverSession().resolve(loadScript(req, name));
212   }
213
214   /**
215    * Loads the specified CSS file and strips CSS comments from the file.
216    *
217    * <p>
218    * Comments are assumed to be Java-style block comments: <js>"/*"</js>.
219    *
220    * @param req The HTTP request object. Must not be <jk>null</jk>.
221    * @param name Name of the desired resource.
222    * @return The resource converted to a string, or <jk>null</jk> if the resource could not be found.
223    */
224   protected String loadStyle(RestRequest req, String name) {
225      try {
226         return getFileFinder(req).getString(name, null).map(s -> s.replaceAll("(?s)\\/\\*(.*?)\\*\\/\\s*", "")).orElse(null);
227      } catch (IOException e) {
228         throw toRex(e);
229      }
230   }
231
232   /**
233    * Same as {@link #loadStyle(RestRequest,String)} but replaces request-time SVL variables.
234    *
235    * <h4 class='section'>See Also:</h4><ul>
236    *    <li class='jm'>{@link RestContext#getVarResolver()}
237    *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerSvlVariables">REST Server SVL Variables</a>
238    * </ul>
239    *
240    * @param req The current HTTP request. Must not be <jk>null</jk>.
241    * @param res The current HTTP response.
242    * @param name Name of the desired resource.
243    * @return The resource converted to a string, or <jk>null</jk> if the resource could not be found.
244    * @throws IOException Thrown by underlying stream.
245    */
246   protected String loadStyleWithVars(RestRequest req, RestResponse res, String name) throws IOException {
247      return req.getVarResolverSession().resolve(loadStyle(req, name));
248   }
249}