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  /**
058   * {@inheritDoc}
059   *
060   * <p>Note that this implementation will only ever allow a single container in the package
061   * container groups. If a container is already present, then an exception will be thrown.
062   *
063   * @param container the container to add.
064   * @throws IllegalStateException if a package already exists in this location.
065   */
066  @Override
067  void addPackage(Container container);
068
069  /**
070   * Get the output-oriented location.
071   *
072   * @return the output-oriented location.
073   */
074  @Override
075  Location getLocation();
076
077  /**
078   * {@inheritDoc}
079   *
080   * <p>Note that this implementation will only ever return one container in the list due to
081   * JSR-199 limitations.
082   *
083   * @return the list containing the package container, if it exists. Otherwise, an empty list is
084   *     returned instead.
085   */
086  @Override
087  List<Container> getPackages();
088}