Interface Project

All Superinterfaces:
ResourceProvider
All Known Subinterfaces:
RootProject
All Known Implementing Classes:
AbstractProject, BootstrapBuild, BootstrapRoot
public interface Project extends ResourceProvider

Projects are used to structure the build configuration. Every build configuration has a single root project and may contain sub-projects. The root project serves as the entry point for the build. Resources provided by the builder are typically provided by the root project, which acts as the central access point of the build configuration.

Projects are ResourceProviders that obtain resources from related ResourceProviders. Conceptually, a project acts as a router for requests and resources, with its behavior depending on the intended usage of the resources obtained from the providers registered as dependencies. The intended usage is indicated by the Intent that attributes the relationship between a project and its related resource providers.

Attributing relationships to providers

Intent Supply

Intent Supply

Resources from a provider added with Intent.Supply are made available by the project to entities that depend on it. Intent.Supply implies that the resources are generated specifically for the project, typically by a Generator that belongs to the project.

Intent Consume and Reveal

Intent Consume

Resources from a provider added with Intent.Consume or Intent.Reveal are typically used only by a project's generators. If a provider is added with Intent.Reveal, its resources are also provided by the project when they are explicitly included in a request.

Intent Expose

Intent Expose

Resources from a provider added with Intent.Expose (typically another project) are used by a project's generators and are also provided by the project to entities that depend on it.

Intent Forward

Intent Forward

Resources from a provider added with Intent.Forward (typically another project) are provided by the project to entities that depend on it. These resources are not intended to be used by the project's generators. This cannot be enforced, however, as generators may still access them via providers().

Behavior as resource provider

In its role as a ResourceProvider, a Project provides resources obtained from its dependencies. A ResourceRequest controls to which dependencies a request is forwarded by including the respective Intents in the set returned by ResourceRequest.uses().

Concepts from other build tools, such as Gradle’s dependency configurations, can be mapped to resource requests for classpath elements using sets of Intents as follows:

Intent \ Config. Api Implementation Compile only Runtime only
SupplyXX
ConsumeX
RevealX
ExposeXX
ForwardX

To ensure consistent results, a project adjusts a request before forwarding it to a dependency of type Project (typically a sub-project). If the request uses Consume or Expose, Consume is removed and Expose and Supply are added. The reason is that, regardless of how a sub-project contributes to another project, the resources it contributes are always those that are part of its API.

To avoid misuse of Intents, all intents are removed from a request before it is forwarded to a dependency that is not a project.

Factory method for resources

As a convenience, this interface also defines a shortcut for creating Resources.

  • Method Details

    • rootProject

      RootProject rootProject()
      Returns the root project.
      Returns:
      the project

    • project

      Project project(Class<? extends Project> project)
      Returns the instance of the given project class. Projects are created lazily by the builder and must be accessed via this method.
      Parameters:
      project - the requested project's type
      Returns:
      the project

    • parentProject

      Optional<Project> parentProject()
      Returns the parent project. The root project has no parent.
      Returns:
      the parent project

    • directory

      Path directory()
      Returns the project's directory.
      Returns:
      the path

    • buildDirectory

      default Path buildDirectory()
      Returns the directory where the project's Generators should create the artifacts. This is short for directory().resolve((Path) get(Properties.BuildDirectory)).
      Returns:
      the path

    • generator

      Project generator(Generator generator)

      Adds a provider to the project that generates resources which are then provided by the project. For "normal" projects, the generated resources are assumed to be provided to dependents of the project, so the invocation is shorthand for
      dependency(Intent.Supply, generator).

      For projects that implement MergedTestProject, generated resources are usually intended to be used by the project itself only, so the invocation is short for dependency(Intent.Consume, generator).

      Parameters:
      generator - the provider
      Returns:
      the project

    • generator

      default <T extends Generator> T generator(Function<Project,T> supplier)

      Uses the supplier to create a provider, passing this project as argument and adds the result as a generator to this project. This is a convenience method to add a provider to the project by writing (in a project's constructor):

      generator(Provider::new);

      instead of:

      generator(new Provider(this));
      Type Parameters:
      T - the generic type
      Parameters:
      supplier - the supplier
      Returns:
      the project for method chaining

    • dependency

      Project dependency(Intent intent, ResourceProvider provider)

      Adds a provider that contributes resources to the project with the given intended usage.

      While this could be used to add a Generator to the project as a provider with Intent.Supply, it is recommended to use one of the "generator" methods for better readability.

      Parameters:
      intent - the dependency type
      provider - the provider
      Returns:
      the project for method chaining
      See Also:

    • dependency

      default <T extends ResourceProvider> T dependency(Intent intent, Function<Project,T> supplier)

      Uses the supplier to create a provider, passing this project as argument and adds the result as a dependency to this project. This is a convenience method to add a provider to the project by writing (in a project's constructor):

      dependency(intent, Provider::new);

      instead of:

      dependency(intent, new Provider(this));
      Type Parameters:
      T - the generic type
      Parameters:
      intent - the intent
      supplier - the supplier
      Returns:
      the project for method chaining

    • providers

      ProviderSelection providers()
      Return a provider selection without any restrictions.
      Returns:
      the provider selection

    • providers

      ProviderSelection providers(Set<Intent> intents)
      Return a provider selection that is restricted to the given intents.
      Parameters:
      intents - the intents
      Returns:
      the provider selection

    • providers

      default ProviderSelection providers(Intent intent, Intent... intents)
      Return a provider selection that is restricted to the given intents.
      Parameters:
      intent - the intent
      intents - the intents
      Returns:
      the provider selection

    • relativize

      default Path relativize(Path other)
      Short for directory().relativize(other).
      Parameters:
      other - the other path
      Returns:
      the relativized path

    • set

      Project set(PropertyKey property, Object value)

      Sets the given property to the given value.

      Regrettably, there is no way to enforce at compile time that the type of the value passed to set matches the type of the property. An implementation must check this at runtime by verifying that the given value is assignable to the default value.

      Parameters:
      property - the property
      value - the value
      Returns:
      the project

    • get

      <T> T get(PropertyKey property)
      Returns value of the given property of the project. If the property is not set, the parent project's value is returned. If neither is set, the property's default value is returned.
      Type Parameters:
      T - the property type
      Parameters:
      property - the property
      Returns:
      the property

    • newResource

      <T extends Resource> T newResource(ResourceType<T> type, Object... args)
      Convenience method to create a new resource. Short for invoking ResourceFactory.create(ResourceType, Project, Object...) with the given type as first argument, the current project as second argument and the remaining given arguments appended.
      Type Parameters:
      T - the resource type
      Parameters:
      type - the type
      args - the arguments
      Returns:
      the resource

    • readString

      default String readString(Path path)
      Convenience method for reading the content of a file into a String. The path is resolved against the project's directory.
      Parameters:
      path - the path
      Returns:
      the string