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