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.view;
018
019import java.io.*;
020
021import org.apache.juneau.rest.server.*;
022
023/**
024 * Engine-agnostic raw-template-dispatch contract shared by the view mixin resources and their
025 * standalone servlet companions.
026 *
027 * <p>
028 * Not to be confused with {@link ViewRenderer} &mdash; that is the response-processor marker that
029 * renders {@link View}-typed {@code @RestOp} return values. This contract instead covers the
030 * <i>raw</i> file-serving path: serving a {@code .jsp} / {@code .ftlh} / {@code .mustache} /
031 * {@code .html} template directly by its trailing request path.
032 *
033 * <p>
034 * The per-engine flavor-neutral worker beans ({@code JspDispatcher}, {@code FreemarkerDispatcher},
035 * {@code MustacheDispatcher}, {@code ThymeleafDispatcher}) implement this interface; the three flavor
036 * classes ({@code <Engine>Mixin} / {@code <Engine>Servlet} / {@code <Engine>Resource}) each hold one
037 * of these workers and delegate to it. Sharing a single implementation at the worker-bean
038 * level means the mixin, servlet, and child forms cannot drift in their file-serving behavior.
039 *
040 * <p>
041 * The single {@link #render(String, RestRequest, RestResponse) render(...)} method receives the
042 * trailing request path (the multi-segment remainder captured by the host's {@code @Path("/*")}
043 * binding), resolves it against the implementation's configured base path, and writes the rendered
044 * output directly onto the response.
045 *
046 * <h5 class='section'>See Also:</h5><ul>
047 *    <li class='jc'>{@link ViewServlet}
048 *    <li class='jic'>{@link ViewRenderer}
049 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerComposition">REST Server — Mixins and Multi-Mount Paths</a>
050 * </ul>
051 *
052 * @since 10.0.0
053 */
054public interface RawTemplateDispatcher {
055
056   /**
057    * Renders the raw template identified by the trailing request path onto the response.
058    *
059    * <p>
060    * Implementations resolve {@code path} against their configured base path (rejecting any
061    * {@code ..} traversal), ask the underlying templating engine for the resource, and write it
062    * to the response writer.  Boundary violations and engine errors surface as
063    * {@link org.apache.juneau.http.response.BasicHttpException BasicHttpException} subtypes
064    * (unchecked), so this method only declares the checked {@link IOException}.
065    *
066    * @param path The trailing path segment after the mount prefix (the template / file name
067    *    relative to the configured base path). May be {@code null} (treated as empty).
068    * @param req The current REST request.
069    * @param res The current REST response.
070    * @throws IOException If the underlying response writer fails.
071    */
072   void render(String path, RestRequest req, RestResponse res) throws IOException;
073}