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
019/**
020 * Minimal shared contract implemented by the builder of every view-engine mixin
021 * ({@code JspMixin.Builder}, {@code ThymeleafMixin.Builder}, {@code MustacheMixin.Builder},
022 * {@code FreemarkerMixin.Builder}).
023 *
024 * <p>
025 * The four view-engine bridges each evolved their own builder independently (worker-bean
026 * composition), and their per-engine knobs legitimately diverge &mdash; e.g. only Thymeleaf exposes
027 * {@code templateMode(...)}, only Mustache/FreeMarker expose {@code templateSuffix(...)}. This
028 * interface pins down the small subset of knobs that are meaningful to <b>every</b> engine, so a
029 * caller who has learned one bridge's shape can rely on these two methods transferring to the
030 * others without re-reading each bridge's Javadoc.
031 *
032 * <p>
033 * Implementations return their own concrete builder type from each method so call chains stay
034 * fluent (e.g. {@code JspMixin.create().basePath(...).build()}); the self-bounded type parameter
035 * {@code <B>} captures that covariant return type.
036 *
037 * <p>
038 * <b>Note on {@code cacheTemplates(boolean)}:</b> not every engine has a real caching knob to back
039 * this with. Bridges that can honor it (e.g. Mustache, FreeMarker, Thymeleaf) apply it to their
040 * bridge-default engine/factory/configuration. The JSP bridge accepts and reports the flag for
041 * interface conformance, but has no effect: JSP recompilation is entirely delegated to the servlet
042 * container via {@code RequestDispatcher.forward(...)}, and containers manage their own JSP
043 * recompilation policy (e.g. Tomcat's {@code development} / {@code modificationTestInterval}
044 * settings) outside this bridge's control. See each {@code *Mixin.Builder#cacheTemplates(boolean)}
045 * override's own Javadoc for the exact per-engine behavior.
046 *
047 * <h5 class='section'>See Also:</h5><ul>
048 *    <li class='link'><a class="doclink" href="https://juneau.apache.org/docs/topics/RestServerComposition">REST Server — Mixins and Multi-Mount Paths</a>
049 * </ul>
050 *
051 * @param <B> The implementing builder's own concrete type.
052 * @since 10.0.0
053 */
054public interface ViewMixinBuilder<B extends ViewMixinBuilder<B>> {
055
056   /**
057    * Sets the base path under which the engine's template resources are resolved.
058    *
059    * @param value The base path. Bridges treat {@code null} / blank as "reset to the bridge's own default".
060    * @return This object (for method chaining).
061    */
062   B basePath(String value);
063
064   /**
065    * Sets whether the bridge's default engine caches resolved/compiled templates.
066    *
067    * <p>
068    * Typically defaults to {@code true} (production-safe); set {@code false} during development
069    * to pick up template edits without restarting the server. See the class-level Javadoc for the
070    * JSP-bridge caveat.
071    *
072    * @param value The cache flag.
073    * @return This object (for method chaining).
074    */
075   B cacheTemplates(boolean value);
076}