JAMES-2325 Allow to exclude some matcher/mailet from documentation
Project: http://git-wip-us.apache.org/repos/asf/james-project/repo Commit: http://git-wip-us.apache.org/repos/asf/james-project/commit/403c70e3 Tree: http://git-wip-us.apache.org/repos/asf/james-project/tree/403c70e3 Diff: http://git-wip-us.apache.org/repos/asf/james-project/diff/403c70e3 Branch: refs/heads/master Commit: 403c70e3f70db50fa95b8de2752eb361dc76e55b Parents: db99281 Author: Michael Schnitzler <schnitzler.michael+git...@gmail.com> Authored: Tue Oct 23 20:10:47 2018 +0200 Committer: Benoit Tellier <btell...@linagora.com> Committed: Wed Oct 24 16:36:16 2018 +0700 ---------------------------------------------------------------------- .../apache/mailet/ExcludeFromDocumentation.java | 29 +++++++++++ .../mailet/DefaultDescriptorsExtractor.java | 13 +++++ .../mailet/DefaultDescriptorsExtractorTest.java | 24 +++++++-- .../apache/james/mailet/ExperimentalMailet.java | 54 -------------------- .../james/mailet/NonExperimentalMailet.java | 52 ------------------- .../ExcludedFromDocumentationMailet.java | 54 ++++++++++++++++++++ .../NotExcludedFromDocumentationMailet.java | 52 +++++++++++++++++++ .../mailet/experimental/ExperimentalMailet.java | 54 ++++++++++++++++++++ .../experimental/NonExperimentalMailet.java | 52 +++++++++++++++++++ 9 files changed, 275 insertions(+), 109 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/james-project/blob/403c70e3/mailet/api/src/main/java/org/apache/mailet/ExcludeFromDocumentation.java ---------------------------------------------------------------------- diff --git a/mailet/api/src/main/java/org/apache/mailet/ExcludeFromDocumentation.java b/mailet/api/src/main/java/org/apache/mailet/ExcludeFromDocumentation.java new file mode 100644 index 0000000..bcd2c72 --- /dev/null +++ b/mailet/api/src/main/java/org/apache/mailet/ExcludeFromDocumentation.java @@ -0,0 +1,29 @@ +/**************************************************************** + * 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 org.apache.mailet; + +import static java.lang.annotation.ElementType.TYPE; + +import java.lang.annotation.Target; + +@Target(TYPE) +public @interface ExcludeFromDocumentation { + +} http://git-wip-us.apache.org/repos/asf/james-project/blob/403c70e3/mailet/mailetdocs-maven-plugin/src/main/java/org/apache/james/mailet/DefaultDescriptorsExtractor.java ---------------------------------------------------------------------- diff --git a/mailet/mailetdocs-maven-plugin/src/main/java/org/apache/james/mailet/DefaultDescriptorsExtractor.java b/mailet/mailetdocs-maven-plugin/src/main/java/org/apache/james/mailet/DefaultDescriptorsExtractor.java index f43ae24..ea4ec1b 100644 --- a/mailet/mailetdocs-maven-plugin/src/main/java/org/apache/james/mailet/DefaultDescriptorsExtractor.java +++ b/mailet/mailetdocs-maven-plugin/src/main/java/org/apache/james/mailet/DefaultDescriptorsExtractor.java @@ -31,6 +31,7 @@ import java.util.List; import java.util.Set; import org.apache.james.mailet.MailetMatcherDescriptor.Type; +import org.apache.mailet.ExcludeFromDocumentation; import org.apache.mailet.Experimental; import org.apache.mailet.Mailet; import org.apache.mailet.Matcher; @@ -98,6 +99,11 @@ public class DefaultDescriptorsExtractor { log.debug("Class: " + nameOfNextClass); } + if (isExcludedFromDocumentation(nextClass)) { + log.debug(nameOfNextClass + " is excluded from documentation"); + return; + } + try { final Class<?> klass = classLoader.loadClass(nameOfNextClass); @@ -187,6 +193,13 @@ public class DefaultDescriptorsExtractor { .anyMatch((JavaAnnotation annotation) -> annotation.getType().getCanonicalName() .equals(Experimental.class.getName())); } + + private boolean isExcludedFromDocumentation(JavaClass javaClass) { + return javaClass.getAnnotations() + .stream() + .anyMatch((JavaAnnotation annotation) -> annotation.getType().getCanonicalName() + .equals(ExcludeFromDocumentation.class.getName())); + } private void handleInfoLoadFailure(Log log, String nameOfClass, final Type type, Exception e) { http://git-wip-us.apache.org/repos/asf/james-project/blob/403c70e3/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/DefaultDescriptorsExtractorTest.java ---------------------------------------------------------------------- diff --git a/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/DefaultDescriptorsExtractorTest.java b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/DefaultDescriptorsExtractorTest.java index a94a8a0..35fa063 100644 --- a/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/DefaultDescriptorsExtractorTest.java +++ b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/DefaultDescriptorsExtractorTest.java @@ -49,19 +49,19 @@ public class DefaultDescriptorsExtractorTest { @Test public void extractShouldSetExperimentalAttributeWhenScanningMailets() { when(mavenProject.getCompileSourceRoots()) - .thenReturn(ImmutableList.of("src/test/java")); + .thenReturn(ImmutableList.of("src/test/java/org/apache/james/mailet/experimental")); List<MailetMatcherDescriptor> descriptors = testee.extract(mavenProject, log) .descriptors(); MailetMatcherDescriptor experimentalMailet = new MailetMatcherDescriptor(); - experimentalMailet.setFullyQualifiedName("org.apache.james.mailet.ExperimentalMailet"); + experimentalMailet.setFullyQualifiedName("org.apache.james.mailet.experimental.ExperimentalMailet"); experimentalMailet.setName("ExperimentalMailet"); experimentalMailet.setInfo(null); experimentalMailet.setType(Type.MAILET); experimentalMailet.setExperimental(true); MailetMatcherDescriptor nonExperimentalMailet = new MailetMatcherDescriptor(); - nonExperimentalMailet.setFullyQualifiedName("org.apache.james.mailet.NonExperimentalMailet"); + nonExperimentalMailet.setFullyQualifiedName("org.apache.james.mailet.experimental.NonExperimentalMailet"); nonExperimentalMailet.setName("NonExperimentalMailet"); nonExperimentalMailet.setInfo(null); nonExperimentalMailet.setType(Type.MAILET); @@ -69,4 +69,22 @@ public class DefaultDescriptorsExtractorTest { assertThat(descriptors).containsOnly(experimentalMailet, nonExperimentalMailet); } + + @Test + public void extractShouldExcludeAnnotatedClassesWhenScanningMailets() { + when(mavenProject.getCompileSourceRoots()) + .thenReturn(ImmutableList.of("src/test/java/org/apache/james/mailet/excluded")); + + List<MailetMatcherDescriptor> descriptors = testee.extract(mavenProject, log) + .descriptors(); + + MailetMatcherDescriptor notExcludedMailet = new MailetMatcherDescriptor(); + notExcludedMailet.setFullyQualifiedName("org.apache.james.mailet.excluded.NotExcludedFromDocumentationMailet"); + notExcludedMailet.setName("NotExcludedFromDocumentationMailet"); + notExcludedMailet.setInfo(null); + notExcludedMailet.setType(Type.MAILET); + notExcludedMailet.setExperimental(false); + + assertThat(descriptors).containsOnly(notExcludedMailet); + } } http://git-wip-us.apache.org/repos/asf/james-project/blob/403c70e3/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/ExperimentalMailet.java ---------------------------------------------------------------------- diff --git a/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/ExperimentalMailet.java b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/ExperimentalMailet.java deleted file mode 100644 index 0506d3f..0000000 --- a/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/ExperimentalMailet.java +++ /dev/null @@ -1,54 +0,0 @@ -/**************************************************************** - * 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 org.apache.james.mailet; - -import javax.mail.MessagingException; - -import org.apache.mailet.Experimental; -import org.apache.mailet.Mail; -import org.apache.mailet.Mailet; -import org.apache.mailet.MailetConfig; - -@Experimental -public class ExperimentalMailet implements Mailet { - - @Override - public void init(MailetConfig config) throws MessagingException { - } - - @Override - public void service(Mail mail) throws MessagingException { - } - - @Override - public void destroy() { - } - - @Override - public MailetConfig getMailetConfig() { - return null; - } - - @Override - public String getMailetInfo() { - return null; - } - -} http://git-wip-us.apache.org/repos/asf/james-project/blob/403c70e3/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/NonExperimentalMailet.java ---------------------------------------------------------------------- diff --git a/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/NonExperimentalMailet.java b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/NonExperimentalMailet.java deleted file mode 100644 index 5031bc0..0000000 --- a/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/NonExperimentalMailet.java +++ /dev/null @@ -1,52 +0,0 @@ -/**************************************************************** - * 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 org.apache.james.mailet; - -import javax.mail.MessagingException; - -import org.apache.mailet.Mail; -import org.apache.mailet.Mailet; -import org.apache.mailet.MailetConfig; - -public class NonExperimentalMailet implements Mailet { - - @Override - public void init(MailetConfig config) throws MessagingException { - } - - @Override - public void service(Mail mail) throws MessagingException { - } - - @Override - public void destroy() { - } - - @Override - public MailetConfig getMailetConfig() { - return null; - } - - @Override - public String getMailetInfo() { - return null; - } - -} http://git-wip-us.apache.org/repos/asf/james-project/blob/403c70e3/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/excluded/ExcludedFromDocumentationMailet.java ---------------------------------------------------------------------- diff --git a/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/excluded/ExcludedFromDocumentationMailet.java b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/excluded/ExcludedFromDocumentationMailet.java new file mode 100644 index 0000000..bf26edf --- /dev/null +++ b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/excluded/ExcludedFromDocumentationMailet.java @@ -0,0 +1,54 @@ +/**************************************************************** + * 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 org.apache.james.mailet.excluded; + +import javax.mail.MessagingException; + +import org.apache.mailet.ExcludeFromDocumentation; +import org.apache.mailet.Mail; +import org.apache.mailet.Mailet; +import org.apache.mailet.MailetConfig; + +@ExcludeFromDocumentation +public class ExcludedFromDocumentationMailet implements Mailet { + + @Override + public void init(MailetConfig config) throws MessagingException { + } + + @Override + public void service(Mail mail) throws MessagingException { + } + + @Override + public void destroy() { + } + + @Override + public MailetConfig getMailetConfig() { + return null; + } + + @Override + public String getMailetInfo() { + return null; + } + +} http://git-wip-us.apache.org/repos/asf/james-project/blob/403c70e3/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/excluded/NotExcludedFromDocumentationMailet.java ---------------------------------------------------------------------- diff --git a/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/excluded/NotExcludedFromDocumentationMailet.java b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/excluded/NotExcludedFromDocumentationMailet.java new file mode 100644 index 0000000..fd45576 --- /dev/null +++ b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/excluded/NotExcludedFromDocumentationMailet.java @@ -0,0 +1,52 @@ +/**************************************************************** + * 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 org.apache.james.mailet.excluded; + +import javax.mail.MessagingException; + +import org.apache.mailet.Mail; +import org.apache.mailet.Mailet; +import org.apache.mailet.MailetConfig; + +public class NotExcludedFromDocumentationMailet implements Mailet { + + @Override + public void init(MailetConfig config) throws MessagingException { + } + + @Override + public void service(Mail mail) throws MessagingException { + } + + @Override + public void destroy() { + } + + @Override + public MailetConfig getMailetConfig() { + return null; + } + + @Override + public String getMailetInfo() { + return null; + } + +} http://git-wip-us.apache.org/repos/asf/james-project/blob/403c70e3/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/experimental/ExperimentalMailet.java ---------------------------------------------------------------------- diff --git a/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/experimental/ExperimentalMailet.java b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/experimental/ExperimentalMailet.java new file mode 100644 index 0000000..1ea2151 --- /dev/null +++ b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/experimental/ExperimentalMailet.java @@ -0,0 +1,54 @@ +/**************************************************************** + * 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 org.apache.james.mailet.experimental; + +import javax.mail.MessagingException; + +import org.apache.mailet.Experimental; +import org.apache.mailet.Mail; +import org.apache.mailet.Mailet; +import org.apache.mailet.MailetConfig; + +@Experimental +public class ExperimentalMailet implements Mailet { + + @Override + public void init(MailetConfig config) throws MessagingException { + } + + @Override + public void service(Mail mail) throws MessagingException { + } + + @Override + public void destroy() { + } + + @Override + public MailetConfig getMailetConfig() { + return null; + } + + @Override + public String getMailetInfo() { + return null; + } + +} http://git-wip-us.apache.org/repos/asf/james-project/blob/403c70e3/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/experimental/NonExperimentalMailet.java ---------------------------------------------------------------------- diff --git a/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/experimental/NonExperimentalMailet.java b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/experimental/NonExperimentalMailet.java new file mode 100644 index 0000000..4ac19ab --- /dev/null +++ b/mailet/mailetdocs-maven-plugin/src/test/java/org/apache/james/mailet/experimental/NonExperimentalMailet.java @@ -0,0 +1,52 @@ +/**************************************************************** + * 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 org.apache.james.mailet.experimental; + +import javax.mail.MessagingException; + +import org.apache.mailet.Mail; +import org.apache.mailet.Mailet; +import org.apache.mailet.MailetConfig; + +public class NonExperimentalMailet implements Mailet { + + @Override + public void init(MailetConfig config) throws MessagingException { + } + + @Override + public void service(Mail mail) throws MessagingException { + } + + @Override + public void destroy() { + } + + @Override + public MailetConfig getMailetConfig() { + return null; + } + + @Override + public String getMailetInfo() { + return null; + } + +} --------------------------------------------------------------------- To unsubscribe, e-mail: server-dev-unsubscr...@james.apache.org For additional commands, e-mail: server-dev-h...@james.apache.org