[Maven Builder Support] Add module maven-builder-support

Add Problem related classes

maven-builder-support/pom.xml

@@ -30,8 +30,8 @@ under the License.
 
   <artifactId>maven-builder-support</artifactId>
 
-  <name>Maven Settings</name>
+  <name>Maven Builder Support</name>
-  <description>Maven Builder Support</description>
+  <description>Support for Builders</description>
 
   <scm><!-- remove when git scm url format can accept artifact-id at the end, as automatically inherited -->
     <connection>scm:git:https://git-wip-us.apache.org/repos/asf/maven.git</connection>

maven-builder-support/src/main/java/org/apache/maven/building/DefaultProblem.java

@@ -0,0 +1,160 @@
+package org.apache.maven.building;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Describes a problem that was encountered during settings building. A problem can either be an exception that was
+ * thrown or a simple string message. In addition, a problem carries a hint about its source, e.g. the settings file
+ * that exhibits the problem.
+ *
+ * @author Benjamin Bentmann
+ * @author Robert Scholte
+ */
+public class DefaultProblem
+    implements Problem
+{
+
+    private final String source;
+
+    private final int lineNumber;
+
+    private final int columnNumber;
+
+    private final String message;
+
+    private final Exception exception;
+
+    private final Severity severity;
+
+    /**
+     * Creates a new problem with the specified message and exception.
+     *
+     * @param message The message describing the problem, may be {@code null}.
+     * @param severity The severity level of the problem, may be {@code null} to default to
+     *            {@link SettingsProblem.Severity#ERROR}.
+     * @param source A hint about the source of the problem like a file path, may be {@code null}.
+     * @param lineNumber The one-based index of the line containing the problem or {@code -1} if unknown.
+     * @param columnNumber The one-based index of the column containing the problem or {@code -1} if unknown.
+     * @param exception The exception that caused this problem, may be {@code null}.
+     */
+    public DefaultProblem( String message, Severity severity, String source, int lineNumber, int columnNumber,
+                                   Exception exception )
+    {
+        this.message = message;
+        this.severity = ( severity != null ) ? severity : Severity.ERROR;
+        this.source = ( source != null ) ? source : "";
+        this.lineNumber = lineNumber;
+        this.columnNumber = columnNumber;
+        this.exception = exception;
+    }
+
+    public String getSource()
+    {
+        return source;
+    }
+
+    public int getLineNumber()
+    {
+        return lineNumber;
+    }
+
+    public int getColumnNumber()
+    {
+        return columnNumber;
+    }
+
+    public String getLocation()
+    {
+        StringBuilder buffer = new StringBuilder( 256 );
+
+        if ( getSource().length() > 0 )
+        {
+            if ( buffer.length() > 0 )
+            {
+                buffer.append( ", " );
+            }
+            buffer.append( getSource() );
+        }
+
+        if ( getLineNumber() > 0 )
+        {
+            if ( buffer.length() > 0 )
+            {
+                buffer.append( ", " );
+            }
+            buffer.append( "line " ).append( getLineNumber() );
+        }
+
+        if ( getColumnNumber() > 0 )
+        {
+            if ( buffer.length() > 0 )
+            {
+                buffer.append( ", " );
+            }
+            buffer.append( "column " ).append( getColumnNumber() );
+        }
+
+        return buffer.toString();
+    }
+
+    public Exception getException()
+    {
+        return exception;
+    }
+
+    public String getMessage()
+    {
+        String msg;
+
+        if ( message != null && message.length() > 0 )
+        {
+            msg = message;
+        }
+        else
+        {
+            msg = exception.getMessage();
+
+            if ( msg == null )
+            {
+                msg = "";
+            }
+        }
+
+        return msg;
+    }
+
+    public Severity getSeverity()
+    {
+        return severity;
+    }
+
+    @Override
+    public String toString()
+    {
+        StringBuilder buffer = new StringBuilder( 128 );
+
+        buffer.append( "[" ).append( getSeverity() ).append( "] " );
+        buffer.append( getMessage() );
+        buffer.append( " @ " ).append( getLocation() );
+
+        return buffer.toString();
+    }
+
+}

maven-builder-support/src/main/java/org/apache/maven/building/DefaultProblemCollector.java

@@ -0,0 +1,63 @@
+package org.apache.maven.building;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import java.util.ArrayList;
+import java.util.List;
+
+/**
+ * Collects problems that are encountered during settings building.
+ *
+ * @author Benjamin Bentmann
+ * @author Robert Scholte
+ */
+class DefaultProblemCollector
+    implements ProblemCollector
+{
+
+    private List<Problem> problems;
+
+    private String source;
+
+    public DefaultProblemCollector( List<Problem> problems )
+    {
+        this.problems = ( problems != null ) ? problems : new ArrayList<Problem>();
+    }
+
+    @Override
+    public List<Problem> getProblems()
+    {
+        return problems;
+    }
+
+    @Override
+    public void setSource( String source )
+    {
+        this.source = source;
+    }
+
+    public void add( Problem.Severity severity, String message, int line, int column, Exception cause )
+    {
+        Problem problem = new DefaultProblem( message, severity, source, line, column, cause );
+
+        problems.add( problem );
+    }
+
+}

maven-builder-support/src/main/java/org/apache/maven/building/Problem.java

@@ -0,0 +1,101 @@
+package org.apache.maven.building;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+/**
+ * Describes a problem that was encountered during settings building. A problem can either be an exception that was
+ * thrown or a simple string message. In addition, a problem carries a hint about its source, e.g. the settings file
+ * that exhibits the problem.
+ *
+ * @author Benjamin Bentmann
+ * @author Robert Scholte
+ */
+public interface Problem
+{
+
+    /**
+     * The different severity levels for a problem, in decreasing order.
+     */
+    enum Severity
+    {
+
+        FATAL, //
+        ERROR, //
+        WARNING //
+
+    }
+
+    /**
+     * Gets the hint about the source of the problem. While the syntax of this hint is unspecified and depends on the
+     * creator of the problem, the general expectation is that the hint provides sufficient information to the user to
+     * track the problem back to its origin. A concrete example for such a source hint can be the file path or URL from
+     * which the settings were read.
+     *
+     * @return The hint about the source of the problem or an empty string if unknown, never {@code null}.
+     */
+    String getSource();
+
+    /**
+     * Gets the one-based index of the line containing the problem. The line number should refer to some text file that
+     * is given by {@link #getSource()}.
+     *
+     * @return The one-based index of the line containing the problem or a non-positive value if unknown.
+     */
+    int getLineNumber();
+
+    /**
+     * Gets the one-based index of the column containing the problem. The column number should refer to some text file
+     * that is given by {@link #getSource()}.
+     *
+     * @return The one-based index of the column containing the problem or non-positive value if unknown.
+     */
+    int getColumnNumber();
+
+    /**
+     * Gets the location of the problem. The location is a user-friendly combination of the values from
+     * {@link #getSource()}, {@link #getLineNumber()} and {@link #getColumnNumber()}. The exact syntax of the returned
+     * value is undefined.
+     *
+     * @return The location of the problem, never {@code null}.
+     */
+    String getLocation();
+
+    /**
+     * Gets the exception that caused this problem (if any).
+     *
+     * @return The exception that caused this problem or {@code null} if not applicable.
+     */
+    Exception getException();
+
+    /**
+     * Gets the message that describes this problem.
+     *
+     * @return The message describing this problem, never {@code null}.
+     */
+    String getMessage();
+
+    /**
+     * Gets the severity level of this problem.
+     *
+     * @return The severity level of this problem, never {@code null}.
+     */
+    Severity getSeverity();
+
+}

maven-builder-support/src/main/java/org/apache/maven/building/ProblemCollector.java

@@ -0,0 +1,58 @@
+package org.apache.maven.building;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import java.util.List;
+
+/**
+ * Collects problems that are encountered during settings building.
+ *
+ * @author Benjamin Bentmann
+ * @author Robert Scholte
+ */
+public interface ProblemCollector
+{
+
+    /**
+     * Adds the specified problem.
+     *
+     * @param severity The severity of the problem, must not be {@code null}.
+     * @param message The detail message of the problem, may be {@code null}.
+     * @param line The one-based index of the line containing the problem or {@code -1} if unknown.
+     * @param column The one-based index of the column containing the problem or {@code -1} if unknown.
+     * @param cause The cause of the problem, may be {@code null}.
+     */
+    void add( Problem.Severity severity, String message, int line, int column, Exception cause );
+    
+    /**
+     * The next messages will be bound to this source. When calling this method again, previous messages keep
+     * their source, but the next messages will use the new source.
+     * 
+     * @param source
+     */
+    void setSource( String source );
+    
+    /**
+     * 
+     * @return the collected Problems
+     */
+    List<Problem> getProblems();
+
+}

maven-builder-support/src/main/java/org/apache/maven/building/ProblemCollectorFactory.java

@@ -0,0 +1,43 @@
+package org.apache.maven.building;
+
+/*
+ * Licensed to the Apache Software Foundation (ASF) under one
+ * or more contributor license agreements.  See the NOTICE file
+ * distributed with this work for additional information
+ * regarding copyright ownership.  The ASF licenses this file
+ * to you under the Apache License, Version 2.0 (the
+ * "License"); you may not use this file except in compliance
+ * with the License.  You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing,
+ * software distributed under the License is distributed on an
+ * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ * KIND, either express or implied.  See the License for the
+ * specific language governing permissions and limitations
+ * under the License.
+ */
+
+import java.util.List;
+
+/**
+ * 
+ * @author Robert Scholte
+ * @since 3.2.6
+ */
+public class ProblemCollectorFactory
+{
+
+    /**
+     * The default implementation is not visible, create it with this factory 
+     * 
+     * @param problems
+     * @return a new instance of a ProblemCollector
+     */
+    public static ProblemCollector newInstance( List<Problem> problems )
+    {
+        return new DefaultProblemCollector( problems );
+    }
+
+}