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.management;
018
019import java.util.*;
020
021import org.apache.juneau.commons.inject.*;
022import org.apache.juneau.http.*;
023import org.apache.juneau.http.response.*;
024import org.apache.juneau.rest.server.*;
025import org.apache.juneau.rest.server.guard.*;
026import org.apache.juneau.rest.server.servlet.*;
027
028/**
029 * Mixin flavor of the {@code /loggers} runtime log-level management endpoint.
030 *
031 * <p>
032 * Composes the logger read/set endpoints into a host resource via
033 * {@link Rest#mixins() @Rest(mixins=LoggersMixin.class)}.  Delegates to a shared {@link LoggersManager}
034 * worker so the mixin and {@link LoggersResource resource} flavors cannot drift.
035 *
036 * <p>
037 * The mixin is annotated with {@link Rest#guards() @Rest(guards=DenyAllGuard.class)}, so every logger path returns
038 * {@code 403 Forbidden} until the importer registers a {@link Bean @Bean}
039 * {@link RestGuardList} factory on the host; that list <b>replaces</b> the annotation-derived deny-all, so pair the
040 * mixin with whatever authentication/authorization the app applies to its management endpoints. Changing a level
041 * through the {@code PUT}/{@code POST} set-level endpoint additionally requires a {@link LoggersSettings} bean with
042 * writes enabled.
043 *
044 * <h2 class='section'>Backend:</h2><ul>
045 *    <li>Drives {@link JulLogBackend java.util.logging} by default; declare a Logback / Log4j2 backend
046 *       explicitly via {@link LoggersSettings.Builder#backend(LogBackend)} &mdash; see {@link LogBackend}.
047 * </ul>
048 *
049 * <h2 class='section'>See Also:</h2><ul>
050 *    <li class='jc'>{@link LoggersResource}
051 *    <li class='jc'>{@link LoggersManager}
052 *    <li class='jc'>{@link LogBackend}
053 * </ul>
054 *
055 * @since 10.0.0
056 */
057@Rest(
058   guards=DenyAllGuard.class
059)
060public class LoggersMixin extends RestMixin {
061
062   private final LoggersManager manager = new LoggersManager();
063
064   /**
065    * [GET /loggers] - All loggers and their configured levels.
066    *
067    * @param req The HTTP request.
068    * @return A sorted map of logger name to configured level (empty string = inherited).
069    */
070   @RestGet(
071      path="/loggers",
072      summary="Runtime logger levels",
073      description="Lists all loggers and their configured levels (empty = inherited from ancestor)."
074   )
075   public Map<String,String> getLoggers(RestRequest req) {
076      return manager.getLevels(req.getContext());
077   }
078
079   /**
080    * [GET /loggers/{name}] - One logger's configured level.
081    *
082    * @param req The HTTP request.
083    * @param name The logger name ("ROOT" for the root logger).
084    * @return The configured level name, empty string if inherited.
085    * @throws NotFound If no logger with that name is registered.
086    */
087   @RestGet(
088      path="/loggers/{name}",
089      summary="Runtime logger level",
090      description="Returns the configured level of a single logger."
091   )
092   public String getLogger(RestRequest req, @Path("name") String name) {
093      var level = manager.getLevel(req.getContext(), name);
094      if (level == null)
095         throw new NotFound("No logger named '%s' is registered.", name);
096      return level;
097   }
098
099   /**
100    * [PUT /loggers/{name}] - Set a logger's level at runtime.
101    *
102    * <p>
103    * <b>Sensitive (mutating) &mdash; deny-by-default:</b> responds {@code 403} unless a {@link LoggersSettings}
104    * bean with writes enabled is registered.
105    *
106    * @param req The HTTP request.
107    * @param name The logger name ("ROOT" for the root logger).
108    * @param level The level name (e.g. FINE, INFO, OFF), or blank to inherit from the ancestor.
109    * @return The newly-configured level (empty string if inherited).
110    * @throws Forbidden If the set-level endpoint is not enabled.
111    */
112   @RestPut(
113      path="/loggers/{name}",
114      summary="Set logger level",
115      description="Sets the java.util.logging level of a single logger at runtime (blank to inherit).  Disabled by default; opt in via LoggersSettings."
116   )
117   public String setLogger(RestRequest req, @Path("name") String name, @Content String level) {
118      if (! manager.resolveSettings(req.getContext()).isWriteEnabled())
119         throw new Forbidden("The /loggers set-level endpoint is disabled.  Register a LoggersSettings bean with write enabled to use it.");
120      manager.setLevel(req.getContext(), name, level);
121      // setLevel creates the logger on demand, so getLevel always returns non-null here (level name or "" if inherited).
122      return manager.getLevel(req.getContext(), name);
123   }
124
125   /**
126    * [POST /loggers/{name}] - Set a logger's level at runtime (POST alias of {@link #setLogger(RestRequest,String,String)}).
127    *
128    * @param req The HTTP request.
129    * @param name The logger name ("ROOT" for the root logger).
130    * @param level The level name, or blank to inherit.
131    * @return The newly-configured level (empty string if inherited).
132    * @throws Forbidden If the set-level endpoint is not enabled.
133    */
134   @RestPost(
135      path="/loggers/{name}",
136      summary="Set logger level",
137      description="Sets the java.util.logging level of a single logger at runtime (blank to inherit).  Disabled by default; opt in via LoggersSettings."
138   )
139   public String setLoggerPost(RestRequest req, @Path("name") String name, @Content String level) {
140      return setLogger(req, name, level);
141   }
142}