/*
 * Copyright 2011 JBoss Inc
 *
 * Licensed 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.
 */

package org.drools.planner.benchmark.api;

import java.io.File;

import org.drools.planner.core.solution.Solution;

public interface ProblemIO {

    /**
     * The file extension does not include the dot that separates it from the base name.
     * @return never null, for example "xml"
     */
    String getFileExtension();

    /**
     * @param inputSolutionFile never null
     * @return never null
     */
    Solution read(File inputSolutionFile);

    /**
     * @param solution never null
     * @param outputSolutionFile never null, parent directory already exists
     */
    void write(Solution solution, File outputSolutionFile);

}

@@ -708,45 +708,915 @@
 n;%0A%0A
-public interface ProblemIO %7B%0A%0A    /**
+/**%0A * Reads or writes a %7B@link Solution%7D from or to a %7B@link File%7D.%0A */%0Apublic interface ProblemIO %7B%0A%0A    /**%0A     * Every %7B@link Solution%7D type potentially has its own file extension.%0A     * If no specific file extension is defined by the use case, the following are recommended:%0A     * %3Cul%3E%0A     *     %3Cli%3EIf this %7B@link ProblemIO%7D implementation serializes to XML, use file extension %22xml%22.%3C/li%3E%0A     *     %3Cli%3EIf this %7B@link ProblemIO%7D implementation serializes to text, use file extension %22txt%22.%3C/li%3E%0A     *     %3Cli%3EIf this %7B@link ProblemIO%7D implementation serializes to binary, use file extension %22dat%22.%3C/li%3E%0A     * %3C/ul%3E%0A     * %3Cp/%3E%0A     * It's good practice that both the input and the output file have the same file extension,%0A     * because an output file should be able to function as an input file.%0A     * If that isn't the case, this method should return the output file extension.%0A     * %3Cp/%3E
 %0A   

Improve javadoc to deal with file extension confusion