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 can have sub-projects. The root project is the entry point for the build. The resources provided by the builder are usually provided by the root project that serves as n entry point to the build configuration.

Projects are ResourceProviders that obtain resources from related ResourceProviders. Projects can be thought of as routers for resources with their behavior depending on the intended usage of the resources from the related providers. The intended usage is specified by the Intend that attributes the relationship between a project and its related resource providers.

Attributing relationships to providers

Intend Supply

Intend Supply

Resources from a provider added with Intend.Supply are provided by the project to entities that depend on the project. Intend.Supply implies that the resources are genuinely generated for the project (typically by a Generator that belongs to the project).

Intend Consume

Intend Consume

Resources from a provider added with Intend.Consume (typically another project) are only available to a project's generators through provided(ResourceRequest).

Intend Expose

Intend Expose

Resources from a provider added with Intend.Expose (typically another project) are provided by the project to entities that depend on the project. They are also available to a project's generators through provided(ResourceRequest).

Intend Forward

Intend Forward

Resources from a provider added with Intend.Forward (typically another project) are provided by the project to entities that depend on the project. They are not intended to be used by a project's generators, although these cannot be prevented from accessing them through ResourceProvider.provide(ResourceRequest).

Factory methods

As a convenience, the interface also defines factory methods for objects used for defining the project.

  • 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

    • name

      String name()
      Returns the project's name.
      Returns:
      the string

    • directory

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

    • context

      BuildContext context()
      Returns the build context.
      Returns:
      the builder configuration

    • 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. This is short for dependency(provider, Intend.Provide).
      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(Intend intend, 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 Intend.Supply, it is recommended to use one of the "generator" methods for better readability.

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

    • dependency

      default <T extends ResourceProvider> T dependency(Intend intend, 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(intend, Provider::new);

      instead of:

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

    • providers

      Stream<ResourceProvider> providers(Set<Intend> intends)
      Returns the providers that have been added with one of the given intended usages as Stream. The stream may only be terminated after all projects have been created.
      Parameters:
      intends - the intends
      Returns:
      the stream

    • providers

      default Stream<ResourceProvider> providers(Intend intend, Intend... intends)
      Returns the providers that have been added with the given intended usage as Stream. This is short for providers(Set.of(intend)).
      Parameters:
      intend - the intend
      intends - more intends
      Returns:
      the stream

    • provided

      default <T extends Resource> Stream<T> provided(ResourceRequest<T> requested)
      Returns all resources that are provided for the given request by providers associated with Intend.Consume or Intend.Expose.
      Type Parameters:
      T - the requested type
      Parameters:
      requested - the requested
      Returns:
      the provided resources

    • 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 generic type
      Parameters:
      property - the property
      Returns:
      the t

    • get

      default <T extends Resource> Stream<T> get(ResourceRequest<T> request)
      Returns resources provided by the project. Short for context().get(this, request).
      Type Parameters:
      T - the generic type
      Parameters:
      request - the request
      Returns:
      the stream

    • from

      default FromHelper from(ResourceProvider provider)
      "Syntactic sugar" that allows to obtain resources from a provider with from(provider).get(resourceRequest) instead of context().get(provider, resourceRequest).
      Parameters:
      provider - the provider
      Returns:
      the stream of resources

    • from

      default FromHelper from(Stream<ResourceProvider> providers)
      Returns a new FromHelper instance for a subsequent call to FromHelper.get(ResourceRequest).
      Parameters:
      providers - the providers
      Returns:
      the stream of resources

    • from

      default FromHelper from(Intend intend, Intend... intends)
      Retrieves the providers with the specified intend(s) (see providers(Set)) and returns a new FromHelper instance for a subsequent call to FromHelper.get(ResourceRequest).
      Parameters:
      intend - the intend
      intends - the intends
      Returns:
      the from helper

    • newResource

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

    • 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