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.compilers; 017 018import io.github.ascopes.jct.ex.JctCompilerException; 019import io.github.ascopes.jct.filemanagers.JctFileManager; 020import java.util.Collection; 021import java.util.List; 022import javax.tools.JavaCompiler; 023import org.apiguardian.api.API; 024import org.apiguardian.api.API.Status; 025import org.jspecify.annotations.Nullable; 026 027/** 028 * Factory for producing {@link JctCompilation} objects by performing a physical compilation with a 029 * compiler. 030 * 031 * @author Ashley Scopes 032 * @since 0.0.1 033 */ 034@API(since = "0.0.1", status = Status.STABLE) 035public interface JctCompilationFactory { 036 037 /** 038 * Create a compilation. 039 * 040 * @param flags the flags to pass to the compiler. 041 * @param fileManager the file manager to use for file management. 042 * @param jsr199Compiler the compiler backend to use. 043 * @param classNames the binary names of the classes to compile. If this is {@code null}, then 044 * classes should be discovered automatically. 045 * @return the compilation result that contains whether the compiler succeeded or failed, amongst 046 * other information. 047 * @throws JctCompilerException if any prerequisites fail, such as no compilation units being 048 * found, or if the underlying JSR-199 compiler raises an unhandled 049 * exception and cannot complete when invoked. 050 * @throws NullPointerException if any inputs are unexpectedly set to {@code null}. 051 */ 052 JctCompilation createCompilation( 053 List<String> flags, 054 JctFileManager fileManager, 055 JavaCompiler jsr199Compiler, 056 @Nullable Collection<String> classNames 057 ); 058}