Author: tchemit Date: 2009-09-29 19:47:52 +0200 (Tue, 29 Sep 2009) New Revision: 600 Added: trunk/src/site/apt/mojoFramework.apt Modified: trunk/src/main/java/org/nuiton/plugin/AbstractPlugin.java trunk/src/site/apt/index.apt trunk/src/site/apt/mojoTestFramework.apt trunk/src/site/site.xml Log: Evolution #66: documentation des frameworks mojo et test mojo Modified: trunk/src/main/java/org/nuiton/plugin/AbstractPlugin.java =================================================================== --- trunk/src/main/java/org/nuiton/plugin/AbstractPlugin.java 2009-09-29 10:32:02 UTC (rev 599) +++ trunk/src/main/java/org/nuiton/plugin/AbstractPlugin.java 2009-09-29 17:47:52 UTC (rev 600) @@ -41,7 +41,7 @@ import org.nuiton.io.MirroredFileUpdater; /** - * Un MOJO de base pour les autres MOJO concrets avec les options communes. + * Base mojo with usefull methods and implementing {@link Plugin} contract. * * @author chemit */ @@ -64,7 +64,7 @@ * <p/> * The method {@link #execute()} invoke this method only and only if : * <ul> - * <li>{@link #checkPackaging()} returns <code>false</code> (filtrer project type, for example).</li> + * <li>{@link #checkPackaging()} returns <code>true</code>.</li> * <li>method {@link #init()} returns <code>true</code>.</li> * </ul> * @@ -132,17 +132,12 @@ return true; } -// /** -// * -// * @return {@code false} if packaging is ok -// * @deprecated since 1.0.3, do nothing!, use now the {@link #checkPackaging()} method instead -// * which return {@code true} is packaging is ok, be ware, the result is not the same -// * than in this method... -// */ -// @Deprecated -// protected boolean ensurePackaging() { -// return false; -// } + /** + * Accept the project's packaging between some given. + * + * @param packages the accepted packaging + * @return {@code true} if the project's packagin is one of the given ones. + */ protected boolean acceptPackaging(Packaging... packages) { String projectPackaging = getProject().getPackaging(); @@ -156,6 +151,12 @@ return false; } + /** + * Accept the project's packaging if not in given one. + * + * @param packages the rejecting packagings + * @return {@code true} if the project's packaging is not in the given ones. + */ protected boolean rejectPackaging(Packaging... packages) { String projectPackaging = getProject().getPackaging(); @@ -170,7 +171,7 @@ } /** - * Does the actual copy of the file and logging. + * Copy a file to a given locationand logging. * * @param srcFile represents the file to copy. * @param destFile file name of destination file. @@ -184,37 +185,21 @@ getLog().info("Copying " + srcFile.getName() + " to " + destFile); PluginHelper.copy(srcFile, destFile); -// FileUtils.copyFile(srcFile, destFile); } catch (Exception e) { throw new MojoExecutionException("Error copying from " + srcFile + " to " + destFile, e); } } -// /** -// * Does the actual copy of the content to a fileand logging. -// * -// * @param content represents the content to writeFile into file. -// * @param destFile file name of destination file. -// * @param encoding encoding to use to writeFile file -// * @throws MojoExecutionException with a message if an -// * error occurs. -// */ -// protected void copyFile(String content, File destFile, String encoding) -// throws MojoExecutionException { -// try { -// getLog().info("Copying content to " + destFile); -// -// PluginHelper.writeString(destFile, content, encoding); -//// InputStream in = new ByteArrayInputStream(content.getBytes(encoding)); -//// RawInputStreamFacade facade = new RawInputStreamFacade(in); -//// -//// FileUtils.copyStreamToFile(facade, destFile); -// -// } catch (Exception e) { -// throw new MojoExecutionException("Error copying content to " + destFile, e); -// } -// } + /** + * Write a {@code content} into the given destination file for the given + * {@code encoding}. + * + * @param destFile location where to write the content + * @param content content ot write in the file + * @param encoding the enconding of the file + * @throws IOException if any pb while writing the content into the file + */ public void writeFile(File destFile, String content, String encoding) throws IOException { PluginHelper.writeString(destFile, content, encoding); } @@ -231,6 +216,15 @@ return f.exists() && f.lastModified() > pomFile.lastModified(); } + /** + * Collects some file. + * + * @param includes includes + * @param excludes excludes + * @param roots root directories to treate + * @param files cache of file detected indexed by their root directory + * @param updater + */ protected void getFilesToTreateForRoots(String[] includes, String[] excludes, List<String> roots, Map<File, String[]> files, MirroredFileUpdater updater) { DirectoryScanner ds = new DirectoryScanner(); @@ -290,6 +284,15 @@ } } + /** + * Collect to some files with a mirror. + * + * @param includes includes + * @param excludes excludes + * @param srcDir the directory to treate + * @param updater an updater (will give the mirrored files) + * @return the map of mirrored files associated to their files in srcDir + */ protected Map<String, String> getFilesToTreate(String[] includes, String[] excludes, File srcDir, MirroredFileUpdater updater) { Map<String, String> result = new java.util.TreeMap<String, String>(); @@ -348,6 +351,12 @@ return result; } + /** + * Add a given directory in maven project's compile source roots (if not + * already present). + * + * @param srcDir the location to include in compile source roots + */ protected void addCompileSourceRoots(File srcDir) { if (!getProject().getCompileSourceRoots().contains(srcDir.getPath())) { if (isVerbose()) { @@ -357,6 +366,12 @@ } } + /** + * Remove a given directory in maven project's compile source roots (if + * present). + * + * @param srcDir the location to remove from compile source roots + */ protected void removeCompileSourceRoots(File srcDir) { if (getProject().getCompileSourceRoots().contains(srcDir.getPath())) { if (isVerbose()) { @@ -366,6 +381,12 @@ } } + /** + * Add a given directory in maven project's test compile source roots (if not + * already present). + * + * @param srcDir the location to include in test compile source roots + */ protected void addTestCompileSourceRoots(File srcDir) { if (!getProject().getTestCompileSourceRoots().contains(srcDir.getPath())) { if (isVerbose()) { @@ -375,6 +396,12 @@ } } + /** + * Remove a given directory in maven project's test compile source roots (if + * present). + * + * @param srcDir the location to remove from test compile source roots + */ protected void removeTestCompileSourceRoots(File srcDir) { if (getProject().getTestCompileSourceRoots().contains(srcDir.getPath())) { if (isVerbose()) { @@ -384,6 +411,11 @@ } } + /** + * Add a new resource location to the maven project (in not already present). + * + * @param dir the new resource location to add + */ protected void addResourceDir(String dir) { boolean added = PluginHelper.addResourceDir(dir, getProject()); if (added) { @@ -391,6 +423,11 @@ } } + /** + * Add a new test resource location to the maven project (in not already present). + * + * @param dir the new resource location to add + */ protected void addTestResourceDir(String dir) { boolean added = PluginHelper.addTestResourceDir(dir, getProject()); if (added) { @@ -398,6 +435,19 @@ } } + /** + * Init mojo classLoader. + * + * @param project the maven project + * @param src the source directory + * @param addSourcesToClassPath a flag to a maven sources to classLoader + * @param testPhase a flag to specify if we are in a test phase (changes the classLoader) + * @param addResourcesToClassPath flag to add maven's resources to classLoader + * @param addCompileClassPath flag to add maven's project compile classPath to classLoader + * @param addProjectClassPath flag to add maven'es project dependecies to classLoader + * @return the new classLoader + * @throws MalformedURLException + */ @SuppressWarnings({"unchecked"}) protected URLClassLoader initClassLoader(MavenProject project, File src, boolean addSourcesToClassPath, boolean testPhase, boolean addResourcesToClassPath, boolean addCompileClassPath, boolean addProjectClassPath) throws MalformedURLException { URLClassLoader loader = null; @@ -465,10 +515,11 @@ } /** + * Obtain the url of a file, if file does not exist, try in the classPath. * - * @param f le fichier de template - * @return l'url du fichier demande - * @throws IOException pour toute erreur de recherche + * @param f the required resource file. + * @return the url of the resource + * @throws IOException for any error while looking up for the url of the resources */ protected URL getTemplate(File f) throws IOException { URL r = null; @@ -481,11 +532,10 @@ } /** - * Vérifie que le fichier donné existe bien (sur le filesystem ou - * dans le class-path). - * - * @param f le fichier que l'on veut vérifié - * @throws IOException pour tout erreur de recherche + * Check that the given resource exists in a simple fs file or in the classPath. + * + * @param f the required resource file. + * @throws IOException for any error while looking up for the resources content. */ protected void checkResource(File f) throws IOException { if (!f.exists()) { Modified: trunk/src/site/apt/index.apt =================================================================== --- trunk/src/site/apt/index.apt 2009-09-29 10:32:02 UTC (rev 599) +++ trunk/src/site/apt/index.apt 2009-09-29 17:47:52 UTC (rev 600) @@ -27,8 +27,6 @@ * {{{add-third-party-mojo.html} helper:add-third-party}} write the licenses of all third-party libraries used in project. - * {{{check-project-files-mojo.html} helper:check-project-files}} check the root module of project has a changelog.txt file. - * {{{help-mojo.html} helper:help}} display help about the plugin (goals, usage). * {{{available-licenses-mojo.html} helper:available-licenses}} display the known licenses of the plugin. @@ -39,7 +37,7 @@ Plugin toolkit overview - {{{mojoFramework.html}Mojo test framework}}. + {{{mojoFramework.html}Mojo framework}}. see {{{apidocs/index.html}javadoc}}. Added: trunk/src/site/apt/mojoFramework.apt =================================================================== --- trunk/src/site/apt/mojoFramework.apt (rev 0) +++ trunk/src/site/apt/mojoFramework.apt 2009-09-29 17:47:52 UTC (rev 600) @@ -0,0 +1,40 @@ +---- +Mojo framework +---- +---- +2009-08-22 +---- + +Introduction + + This document explains the mojo framework api of <maven-helper-plugin>. + + The <mojo framework> aims to simplify the writing of new mojos. + + To use this framework, your mojo classes <<MUST>> implement the contract + <<org.nuiton.plugin.Plugin>>. + + The framework use these technologies : + + * <<java 6>> + + * <<maven 2.2.1>> + +How to use it + + Implements the <<org.nuiton.plugin.AbstractPlugin>> class. + + There is some filtering methods : + + * <<checkPackaging>> to test if can perform mojo for the project's packaging. + + * <<init>> : initialize the mojo, and return <<true>> if can execute the mojo. + + The core method is the <<doAction>> one, put there your logic. + +Usefull methods + + The <<org.nuiton.plugin.AbstractPlugin>> contains some usefull methods to work + around the maven project and io operations on the files of the project. + + For more explanations, see the {{{apidocs/index.html}javadoc}}. Modified: trunk/src/site/apt/mojoTestFramework.apt =================================================================== --- trunk/src/site/apt/mojoTestFramework.apt 2009-09-29 10:32:02 UTC (rev 599) +++ trunk/src/site/apt/mojoTestFramework.apt 2009-09-29 17:47:52 UTC (rev 600) @@ -1,5 +1,5 @@ ---- -Test framework api +Mojo Test framework ---- ---- 2009-08-22 @@ -17,6 +17,8 @@ The framework use these technologies : * <<java 6>> + + * <<maven 2.2.1>> * <<junit 4.7>> Modified: trunk/src/site/site.xml =================================================================== --- trunk/src/site/site.xml 2009-09-29 10:32:02 UTC (rev 599) +++ trunk/src/site/site.xml 2009-09-29 17:47:52 UTC (rev 600) @@ -43,7 +43,6 @@ <item name="add-license" href="add-license-mojo.html"/> <item name="add-third-party" href="add-third-party-mojo.html"/> <item name="available-licenses" href="available-licenses-mojo.html"/> - <item name="check-project-files" href="check-project-files-mojo.html"/> <item name="send-email" href="send-email-mojo.html"/> <item name="collect-files" href="collect-files-mojo.html"/> <item name="help" href="help-mojo.html"/> @@ -52,6 +51,7 @@ </menu> <menu name="Développeur"> + <item name="Mojo framework" href="mojoFramework.html"/> <item name="Mojo test framework" href="mojoTestFramework.html"/> <item name="A faire" href="Todo.html"/> </menu>