001/* 002 * Copyright (C) 2022 - 2024, the original author or authors. 003 * 004 * Licensed under the Apache License, Version 2.0 (the "License"); 005 * you may not use this file except in compliance with the License. 006 * You may obtain a copy of the License at 007 * 008 * http://www.apache.org/licenses/LICENSE-2.0 009 * 010 * Unless required by applicable law or agreed to in writing, software 011 * distributed under the License is distributed on an "AS IS" BASIS, 012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 013 * See the License for the specific language governing permissions and 014 * limitations under the License. 015 */ 016package io.github.ascopes.jct.filemanagers.config; 017 018import io.github.ascopes.jct.filemanagers.JctFileManager; 019import java.util.LinkedList; 020import java.util.List; 021import org.apiguardian.api.API; 022import org.apiguardian.api.API.Status; 023import org.slf4j.Logger; 024import org.slf4j.LoggerFactory; 025 026/** 027 * A collection representing a chain of configurers to apply to a file manager. 028 * 029 * <p>This is used to provide a set of ordered configuration operations to perform on newly 030 * created file managers to prepare them for consumption in test cases. Common operations 031 * may include: 032 * 033 * <ul> 034 * <li>Automatically configuring the annotation processor paths;</li> 035 * <li>Creating empty locations to prevent compilers raising exceptions;</li> 036 * <li>Installing logging interceptors.</li> 037 * </ul> 038 * 039 * <p>When configuring a file manager with this chain, each configurer is invoked in the 040 * provided order. Configurers themselves must return a file manager as a result of the 041 * configure operation. This operation may return the input file manager if the operation 042 * mutated the input, or it may return a different file manager instance. In the latter 043 * case, subsequent configuration operations internally will use the new file manager. 044 * The last returned file manager in the chain will be used as the final returned result. 045 * This enables configurers to wrap file managers in proxies or delegating implementations 046 * to intercept or override existing behaviours. 047 * 048 * <p>This class is not thread-safe. 049 * 050 * @author Ashley Scopes 051 * @since 0.0.1 052 */ 053@API(since = "0.0.1", status = Status.STABLE) 054public final class JctFileManagerConfigurerChain { 055 056 private static final Logger log = LoggerFactory.getLogger(JctFileManagerConfigurerChain.class); 057 058 private final LinkedList<JctFileManagerConfigurer> configurers; 059 060 /** 061 * Initialise this chain. 062 */ 063 public JctFileManagerConfigurerChain() { 064 configurers = new LinkedList<>(); 065 } 066 067 /** 068 * Add a configurer to the start of the chain. 069 * 070 * @param configurer the configurer to add. 071 * @return this chain for further calls. 072 */ 073 public JctFileManagerConfigurerChain addFirst(JctFileManagerConfigurer configurer) { 074 configurers.addFirst(configurer); 075 return this; 076 } 077 078 /** 079 * Add a configurer to the end of the chain. 080 * 081 * @param configurer the configurer to add. 082 * @return this chain for further calls. 083 */ 084 public JctFileManagerConfigurerChain addLast(JctFileManagerConfigurer configurer) { 085 configurers.addLast(configurer); 086 return this; 087 } 088 089 /** 090 * Get an immutable copy of the list of configurers. 091 * 092 * @return the list of configurers. 093 */ 094 public List<JctFileManagerConfigurer> list() { 095 return List.copyOf(configurers); 096 } 097 098 /** 099 * Apply each configurer to the given file manager in order. 100 * 101 * @param fileManager the file manager to configure. 102 * @return the configured file manager to use. This may or may not be the same object as the input 103 * parameter, depending on how the configurers manipulate the input object. 104 */ 105 public JctFileManager configure(JctFileManager fileManager) { 106 for (var configurer : configurers) { 107 if (configurer.isEnabled()) { 108 log.debug("Applying {} to file manager {}", configurer, fileManager); 109 // Configurers can totally replace the existing file manager 110 // if they choose. 111 fileManager = configurer.configure(fileManager); 112 } else { 113 log.trace("Skipping {}", configurer); 114 } 115 } 116 return fileManager; 117 } 118}