| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| ~~ 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. |
| ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ |
| --- |
| Custom Types |
| --- |
| |
| Custom Types |
| |
| It is possible to provide license matchers or license families of |
| your own by implementing one of the Rat interfaces and providing the |
| implementation as an Ant type. This example will show how to use a |
| custom license matcher. |
| |
| To be suitable as an Ant type your class must provide a public no-arg |
| constructor (or no constructor at all). If you want to support |
| configuration of your instance via XML attributes or nested elements |
| your type must provide methods that follow Ant's method naming |
| conventions. For details see the |
| {{{http://ant.apache.org/manual/develop.html#writingowntask} Writing |
| Your Own Task}} section in Ant's manual. |
| |
| For this example let us assume you want to match a license that looks |
| like |
| |
| ------------------------------------------------------------------ |
| /** |
| * Yet Another Software License, 1.0 |
| * |
| * Lots of text, specifying the users rights, and whatever ... |
| */ |
| ------------------------------------------------------------------ |
| |
| and to make things a bit more interesting the version number shall be |
| configurable as an attribute on your type. |
| |
| An implementation of this matcher could look like |
| |
| ------------------------------------------------------------------ |
| package org.example; |
| |
| import org.apache.rat.analysis.IHeaderMatcher; |
| import org.apache.rat.analysis.RatHeaderAnalysisException; |
| import org.apache.rat.api.Document; |
| import org.apache.rat.api.MetaData; |
| import org.apache.rat.api.MetaData.Datum; |
| |
| /** Just a POJO with no constructor at all */ |
| public class YASLMatcher implements IHeaderMatcher { |
| private final String MATCH = "Yet Another Software License, "; |
| private final String FAMILY = "YASL"; |
| private final String ONE = "1.0"; |
| private String matchWithVersion = MATCH + ONE; |
| private String familyWithVersion = FAMILY + ONE; |
| |
| /** becomes the version attribute */ |
| public void setVersion(String v) { |
| matchWithVersion = MATCH + v; |
| familyWithVersion = FAMILY + v; |
| } |
| |
| public void reset() { } |
| |
| /** trivial implementation that looks for a fixed string */ |
| public boolean match(Document subject, String line) |
| throws RatHeaderAnalysisException { |
| if (line.indexOf(matchWithVersion) >= 0) { |
| // this is what matchers are supposed to do when they find a |
| // match, even though it is not documented very well |
| subject.getMetaData().set(new Datum(MetaData.RAT_URL_LICENSE_FAMILY_CATEGORY, |
| familyWithVersion)); |
| return true; |
| } |
| return false; |
| } |
| } |
| ------------------------------------------------------------------ |
| |
| Actually it would be easier to use Rat's |
| <<<SimplePatternBasedLicense>>> implementation or the built-in |
| {{{../types.html#substringMatcher}<<<substringMatcher>>>}}, but this |
| is just an example. |
| |
| In order to use your matcher it has to be defined as an Ant type. |
| You do so by either using |
| {{{http://ant.apache.org/manual/Tasks/typedef.html} <<<typedef>>>}} or |
| {{{http://ant.apache.org/manual/Tasks/componentdef.html} |
| <<<componentdef>>>}}. If you are using Ant 1.8.x you should use |
| <<<componentdef>>>. |
| |
| In the most simple case this means |
| |
| ------------------------------------------------------------------ |
| <componentdef name="yasl" |
| classname="org.example.YASLMatcher"/> |
| ------------------------------------------------------------------ |
| |
| Since you will be using classes from Rat's core in both the Report |
| task and your implementation you must ensure they get loaded via the |
| same classloader. If you are using the <<<-lib>>> command line |
| switch Rat's core will be part of Ant's core classloader and you don't |
| need to reference it in the <<<typedef>>> for <<<yasl>>> at all. |
| |
| If you define the Rat Antlib via a <<<taskdef>>> task with a nested |
| <<<classpath>>> then you just use the same <<<classpath>>> when |
| defining your custom matcher as well and set <<<loaderRef>>> to the |
| same name. I.e. |
| |
| ------- |
| <path id="rat-classpath"> |
| <pathelement location="YOUR-PATH-TO/apache-rat-${version}.jar"/> |
| <pathelement location="YOUR-PATH-TO/yasl-matcher.jar"/> |
| </path> |
| <taskdef |
| classpathref="rat-classpath" |
| loaderref="rat-classloader" |
| resource="org/apache/rat/anttasks/antlib.xml"> |
| </taskdef> |
| <componentdef name="yasl" |
| classpathref="rat-classpath" |
| loaderref="rat-classloader" |
| classname="org.example.YASLMatcher"/> |
| ------- |
| |
| With a definition like this you can use your matcher as in |
| |
| ------ |
| <report> |
| <fileset dir="src"/> |
| <yasl/> |
| </report> |
| ----- |
| |
| to detect Version 1.0 or |
| |
| ------ |
| <report> |
| <fileset dir="src"/> |
| <yasl version="2.0"/> |
| </report> |
| ----- |
| |
| for 2.0. |