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.containers; 017 018import io.github.ascopes.jct.workspaces.PathRoot; 019import java.util.List; 020import javax.tools.JavaFileManager.Location; 021import org.apiguardian.api.API; 022import org.apiguardian.api.API.Status; 023 024/** 025 * A base definition for an output-oriented container group. 026 * 027 * <p>These can behave as if they are module-oriented, or non-module-oriented. 028 * It is down to the implementation to mediate access between modules and their files. 029 * 030 * <p>Operations on modules should first {@link #getModule(String) get} or 031 * {@link #getOrCreateModule(String) create} the module, and then operate on that sub-container 032 * group. Operations on non-module packages should operate on this container group directly. 033 * 034 * <p>Note that each container group will usually only support one package container group 035 * in the outputs. This is due to the JSR-199 API not providing a method for specifying which output 036 * location to write files to for legacy-style packages. 037 * 038 * @author Ashley Scopes 039 * @since 0.0.1 040 */ 041@API(since = "0.0.1", status = Status.STABLE) 042public interface OutputContainerGroup extends PackageContainerGroup, ModuleContainerGroup { 043 044 /** 045 * {@inheritDoc} 046 * 047 * <p>Note that this implementation will only ever allow a single container in the package 048 * container groups. If a container is already present, then an exception will be thrown. 049 * 050 * @param path the path to add. 051 * @throws IllegalStateException if a package already exists in this location. 052 */ 053 @Override 054 void addPackage(PathRoot path); 055 056 /** 057 * {@inheritDoc} 058 * 059 * <p>Note that this implementation will only ever allow a single container in the package 060 * container groups. If a container is already present, then an exception will be thrown. 061 * 062 * @param container the container to add. 063 * @throws IllegalStateException if a package already exists in this location. 064 */ 065 @Override 066 void addPackage(Container container); 067 068 /** 069 * Get the output-oriented location. 070 * 071 * @return the output-oriented location. 072 */ 073 @Override 074 Location getLocation(); 075 076 /** 077 * {@inheritDoc} 078 * 079 * <p>Note that this implementation will only ever return one container in the list due to 080 * JSR-199 limitations. 081 * 082 * @return the list containing the package container, if it exists. Otherwise, an empty list is 083 * returned instead. 084 */ 085 @Override 086 List<Container> getPackages(); 087}