/*
*
* 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.
*
*/
package flex2.tools.oem;
import java.io.IOException;
import java.io.Writer;
/**
* The <code>Report</code> interface provides information about the composition
* of an <code>Application</code> or a <code>Library</code>.
*
* @see flex2.tools.oem.Builder#getReport()
* @version 2.0.1
* @author Clement Wong
*/
public interface Report
{
/**
* Use this constant when querying information from the compiler.
*/
Object COMPILER = "COMPILER";
/**
* Use this constant when querying information from the linker.
*/
Object LINKER = "LINKER";
/**
* Gets the name of all the sources that are involved in the <code>Application</code> or <code>Library</code>.
* The <code>getSourceNames(Report.COMPILER)</code> method returns the name of all the source files
* that are involved in the compilation.
*
* <p>
* The <code>getSourceNames(Report.LINKER)</code> method returns the name of all the source files
* that are eventually output by the linker.
*
* <p>
* The <code>getSourceNames(Report.COMPILER)</code>
* and <code>getSourceNames(Report.LINKER)</code> methods can yield different results if the linker is
* instructed to exclude certain definitions from the final output.
*
* @see #COMPILER
* @see #LINKER
*
* @param report The <code>COMPILER</code> or <code>LINKER</code>.
*
* @return A list of source names.
*/
String[] getSourceNames(Object report);
/**
* Gets the names of all the assets that are involved in the <code>Application</code> or <code>Library</code>.
* The <code>getAssetNames(Report.COMPILER)</code> method returns the names of all the asset files
* that are involved in the compilation.
*
* <p>
* The <code>getAssetNames(Report.LINKER)</code> method returns the names of all the asset files
* that are eventually output by the linker.
*
* <p>
* The <code>getAssetNames(Report.COMPILER)</code>
* and <code>getAssetNames(Report.LINKER)</code> methods can yield different results if the linker is
* instructed to exclude certain definitions from the final output.
*
* @see #COMPILER
* @see #LINKER
*
* @param report The <code>COMPILER</code> or <code>LINKER</code>.
*
* @return A list of asset names.
*/
String[] getAssetNames(Object report);
/**
* Gets the names of all the assets that are in the specified frame.
* The number of frames in the movie can be obtained by invoking <code>getFrameCount()</code>.
*
* <p>
* If the compilation did not generate a movie, this method returns <code>null</code>.
*
* @see #getFrameCount()
* @param frame frame number. The number is 1-based.
* @return an array of asset file names
*/
String[] getAssetNames(int frame);
/**
* Gets the name of all the libraries that are involved in the <code>Application</code> or <code>Library</code>.
* The <code>getLibraryNames(Report.COMPILER)</code> method returns the name of all the library files
* that are involved in the compilation.
*
* <p>
* The <code>getLibraryNames(Report.LINKER)</code> method returns the name of all the library files
* that are eventually output by the linker.
*
* <p>
* The <code>getLibraryNames(Report.COMPILER)</code>
* and <code>getLibraryNames(Report.LINKER)</code> methods can yield different results if the linker is
* instructed to exclude certain definitions from the final output.
*
* @see #COMPILER
* @see #LINKER
*
* @param report The <code>COMPILER</code> or <code>LINKER</code>.
*
* @return A list of library names.
*/
String[] getLibraryNames(Object report);
/**
* Gets the name of all the resource bundles that are involved in the Application/Library.
* The <code>getResourceBundleNames()</code> method returns a list of names that
* can be passed to the <code>Library.addResourceBundle()</code> method.
*
* <p>
* The returned value should match the output from the <code>resource-bundle-list</code> compiler option.
*
* @return A list of resource bundle names.
*/
String[] getResourceBundleNames();
/**
* Gets the list of all the top-level, externally-visible definitions in the specified
* source file. You can get the specified source file from the <code>getSourceNames()</code> method.
*
* <p>
* The output definition names are in the QName format; for example: <code>mx.controls:Button</code>.
*
* @param sourceName Source file name.
* @return An array of definition names; <code>null</code> if there is no definition in the source file.
*/
String[] getDefinitionNames(String sourceName);
/**
* Gets the list of all the top-level, externally-visible definitions in the specified frame.
* The sequence represents the order in which the definitions are exported to the frame.
* The number of frames in the movie can be obtained by invoking <code>getFrameCount()</code>.
*
* <p>
* If the compilation did not generate a movie, this method returns <code>null</code>.
*
* @see #getFrameCount()
* @param frame frame number. The number is 1-based.
* @return an array of definition names
*/
String[] getDefinitionNames(int frame);
/**
* Gets the location of the specified definition.
*
* <p>
* The specified definition name must be in the QName format; for example: <code>mx.controls:Button</code>.
*
* @param definition A definition is a class, function, variable, or namespace.
* @return The location of the specified definition; <code>null</code> if the definition is not found.
*/
String getLocation(String definition);
/**
* Gets the list of definitions that the specified definition depends on during initialization.
*
* <p>
* The specified definition name must be in the QName format; for example: <code>mx.controls:Button</code>.
*
* @param definition A class.
*
* @return An array of definition names; <code>null</code> if there is no dependency.
*/
String[] getPrerequisites(String definition);
/**
* Gets the list of definitions that the specified definition depends on during run time.
*
* <p>
* The specified definition name must be in the QName format; for example: <code>mx.controls:Button</code>.
*
* @param definition A definition is a class, function, variable, or namespace.
*
* @return An array of definition names; <code>null</code> if there is no dependency.
*/
String[] getDependencies(String definition);
/**
* Writes the linker report to the specified output. If this <code>Report</code> was generated before linking,
* this method returns <code>0</code>. You should provide a <code>BufferedWriter</code>, if possible.
* You should be sure to close the specified <code>Writer</code>.
*
* <p>
* To use this method, you must call the <code>Configuration.keepLinkReport()</code> method
* before the compilation.
*
* @param out An instance of <code>Writer</code>.
*
* @return The number of characters written out.
*
* @throws IOException Thrown when an I/O error occurs while the link report is being written.
*
* @see flex2.tools.oem.Configuration#keepLinkReport(boolean)
*/
long writeLinkReport(Writer out) throws IOException;
/**
* Writes the linker size report to the specified output. If this <code>Report</code> was generated before linking,
* this method returns <code>0</code>. You should provide a <code>BufferedWriter</code>, if possible.
* You should be sure to close the specified <code>Writer</code>.
*
* <p>
* To use this method, you must call the <code>Configuration.keepSizeReport()</code> method
* before the compilation.
*
* @param out An instance of <code>Writer</code>.
*
* @return The number of characters written out.
*
* @throws IOException Thrown when an I/O error occurs while the link report is being written.
*
* @see flex2.tools.oem.Configuration#keepSizeReport(boolean)
*/
long writeSizeReport(Writer out) throws IOException;
/**
* Writes the configuration report to the specified output.
* You should provide a <code>BufferedWriter</code>, if possible.
* Be sure to close the specified <code>Writer</code>.
*
* <p>
* To use this method, you must call the <code>Configuration.keepConfigurationReport()</code> method
* before the compilation.
*
* @param out An instance of <code>Writer</code>.
*
* @return The number of characters written out.
*
* @throws IOException Thrown when an I/O error occurs during writing the configuration report.
*
* @see flex2.tools.oem.Configuration#keepConfigurationReport(boolean)
*/
long writeConfigurationReport(Writer out) throws IOException;
/**
* Gets the background color. The default value is <code>0x869CA7</code>.
* If the <code>Report</code> was generated before linking, this method returns <code>0</code>.
*
* @return An RGB value.
*/
int getBackgroundColor();
/**
* Gets the page title.
* If the <code>Report</code> was generated before linking, this method returns <code>null</code>.
*
* @return Page title; <code>null</code> if it was not specified.
*/
String getPageTitle();
/**
* Gets the default width of the application. The default value is <code>500</code>.
*
* @return The default width, in pixels.
*/
int getDefaultWidth();
/**
* Gets the default height of the application. The default value is <code>375</code>.
*
* @return The default height, in pixels.
*/
int getDefaultHeight();
/**
* Gets the user-defined width.
* If the <code>Report</code> was generated before linking, this method returns <code>0</code>.
*
* @return Width of the application, in pixels; <code>0</code> if it was not specified.
*/
int getWidth();
/**
* Gets the user-defined height.
* If the <code>Report</code> was generated before linking, this method returns <code>0</code>.
*
* @return Height, in pixels; <code>0</code> if it was not specified.
*/
int getHeight();
/**
* Gets the user-defined width percentage.
* If the <code>Report</code> was generated before linking, this method returns <code>0.0</code>.
*
* @return Width percentage; <code>0.0</code> if it was not specified.
*/
double getWidthPercent();
/**
* Gets the user-defined height percentage.
* If the <code>Report</code> was generated before linking, this method returns <code>0.0</code>.
*
* @return Height percentage; <code>0.0</code> if it was not specified.
*/
double getHeightPercent();
/**
* Outputs the compiler version.
*
* @return A string representing the compiler version.
*/
String getCompilerVersion();
/**
* Reports the errors and warnings that were generated during the compilation. The returned
* <code>Message</code> objects are errors and warnings.
*
* @return An array of error and warning Message objects; <code>null</code> if there were no errors or warnings.
*/
Message[] getMessages();
/**
* Gets the number of frames in the movie. For <code>Application</code>, the returned
* value is the number of frames in the movie. For <code>Library</code>, the returned
* value is the number of frames in library.swf.
*
* <p>
* If the compilation did not generate a movie, the returned value will be <code>0</code>.
*
* @return number of frames
*/
int getFrameCount();
/**
* Checks whether the sources, assets and libraries have been updated since the report was created.
*
* @since 3.0
* @return
*/
boolean contentUpdated();
}