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}