Component docs
Project: http://git-wip-us.apache.org/repos/asf/camel/repo Commit: http://git-wip-us.apache.org/repos/asf/camel/commit/a4e69971 Tree: http://git-wip-us.apache.org/repos/asf/camel/tree/a4e69971 Diff: http://git-wip-us.apache.org/repos/asf/camel/diff/a4e69971 Branch: refs/heads/master Commit: a4e69971dfb8e32f421da5908bdc1cf3528a0043 Parents: 08c850e Author: Claus Ibsen <davscl...@apache.org> Authored: Sun Jun 14 11:28:11 2015 +0200 Committer: Claus Ibsen <davscl...@apache.org> Committed: Sun Jun 14 13:08:08 2015 +0200 ---------------------------------------------------------------------- .../file/remote/SftpConfiguration.java | 47 ++++++++++++++++++- .../camel/component/http/HttpEndpoint.java | 29 +++++++++--- .../camel/component/scp/ScpConfiguration.java | 22 ++++++++- .../component/servlet/ServletComponent.java | 6 +++ .../component/servlet/ServletEndpoint.java | 2 +- .../camel/tools/apt/DocumentationHelper.java | 48 ++++++++++++++++---- .../tools/apt/EndpointAnnotationProcessor.java | 24 ++++++++-- 7 files changed, 153 insertions(+), 25 deletions(-) ---------------------------------------------------------------------- http://git-wip-us.apache.org/repos/asf/camel/blob/a4e69971/components/camel-ftp/src/main/java/org/apache/camel/component/file/remote/SftpConfiguration.java ---------------------------------------------------------------------- diff --git a/components/camel-ftp/src/main/java/org/apache/camel/component/file/remote/SftpConfiguration.java b/components/camel-ftp/src/main/java/org/apache/camel/component/file/remote/SftpConfiguration.java index f7b21e8..ac24e7c 100644 --- a/components/camel-ftp/src/main/java/org/apache/camel/component/file/remote/SftpConfiguration.java +++ b/components/camel-ftp/src/main/java/org/apache/camel/component/file/remote/SftpConfiguration.java @@ -43,7 +43,7 @@ public class SftpConfiguration extends RemoteFileConfiguration { @UriParam private String privateKeyPassphrase; private KeyPair keyPair; - @UriParam(defaultValue = "no") + @UriParam(defaultValue = "no", enums = "no,yes") private String strictHostKeyChecking = "no"; @UriParam private int serverAliveInterval; @@ -77,6 +77,9 @@ public class SftpConfiguration extends RemoteFileConfiguration { return knownHostsFile; } + /** + * Sets the known_hosts file, so that the SFTP endpoint can do host key verification. + */ public void setKnownHostsFile(String knownHostsFile) { this.knownHostsFile = knownHostsFile; } @@ -85,6 +88,9 @@ public class SftpConfiguration extends RemoteFileConfiguration { return knownHostsUri; } + /** + * Sets the known_hosts file (loaded from classpath by default), so that the SFTP endpoint can do host key verification. + */ public void setKnownHostsUri(String knownHostsUri) { this.knownHostsUri = knownHostsUri; } @@ -101,6 +107,9 @@ public class SftpConfiguration extends RemoteFileConfiguration { return privateKeyFile; } + /** + * Set the private key file to that the SFTP endpoint can do private key verification. + */ public void setPrivateKeyFile(String privateKeyFile) { this.privateKeyFile = privateKeyFile; } @@ -109,6 +118,9 @@ public class SftpConfiguration extends RemoteFileConfiguration { return privateKeyUri; } + /** + * Set the private key file (loaded from classpath by default) to that the SFTP endpoint can do private key verification. + */ public void setPrivateKeyUri(String privateKeyUri) { this.privateKeyUri = privateKeyUri; } @@ -117,6 +129,9 @@ public class SftpConfiguration extends RemoteFileConfiguration { return privateKey; } + /** + * Set the private key as byte[] to that the SFTP endpoint can do private key verification. + */ public void setPrivateKey(byte[] privateKey) { this.privateKey = privateKey; } @@ -125,6 +140,9 @@ public class SftpConfiguration extends RemoteFileConfiguration { return privateKeyPassphrase; } + /** + * Set the private key file passphrase to that the SFTP endpoint can do private key verification. + */ public void setPrivateKeyPassphrase(String privateKeyFilePassphrase) { this.privateKeyPassphrase = privateKeyFilePassphrase; } @@ -151,10 +169,16 @@ public class SftpConfiguration extends RemoteFileConfiguration { return strictHostKeyChecking; } + /** + * Sets whether to use strict host key checking. + */ public void setStrictHostKeyChecking(String strictHostKeyChecking) { this.strictHostKeyChecking = strictHostKeyChecking; } + /** + * Allows you to set the serverAliveInterval of the sftp session + */ public void setServerAliveInterval(int serverAliveInterval) { this.serverAliveInterval = serverAliveInterval; } @@ -163,6 +187,9 @@ public class SftpConfiguration extends RemoteFileConfiguration { return serverAliveInterval; } + /** + * Allows you to set the serverAliveCountMax of the sftp session + */ public void setServerAliveCountMax(int serverAliveCountMax) { this.serverAliveCountMax = serverAliveCountMax; } @@ -171,6 +198,9 @@ public class SftpConfiguration extends RemoteFileConfiguration { return serverAliveCountMax; } + /** + * Allows you to set chmod on the stored file. For example chmod=640. + */ public void setChmod(String chmod) { this.chmod = chmod; } @@ -179,6 +209,11 @@ public class SftpConfiguration extends RemoteFileConfiguration { return chmod; } + /** + * Set a comma separated list of ciphers that will be used in order of preference. + * Possible cipher names are defined by JCraft JSCH. Some examples include: aes128-ctr,aes128-cbc,3des-ctr,3des-cbc,blowfish-cbc,aes192-cbc,aes256-cbc. + * If not specified the default list from JSCH will be used. + */ public void setCiphers(String ciphers) { this.ciphers = ciphers; } @@ -191,10 +226,18 @@ public class SftpConfiguration extends RemoteFileConfiguration { return compression; } + /** + * To use compression. Specify a level from 1 to 10. + * Important: You must manually add the needed JSCH zlib JAR to the classpath for compression support. + */ public void setCompression(int compression) { this.compression = compression; } - + + /** + * Set the preferred authentications which SFTP endpoint will used. Some example include:password,publickey. + * If not specified the default list from JSCH will be used. + */ public void setPreferredAuthentications(String pAuthentications) { this.preferredAuthentications = pAuthentications; } http://git-wip-us.apache.org/repos/asf/camel/blob/a4e69971/components/camel-http/src/main/java/org/apache/camel/component/http/HttpEndpoint.java ---------------------------------------------------------------------- diff --git a/components/camel-http/src/main/java/org/apache/camel/component/http/HttpEndpoint.java b/components/camel-http/src/main/java/org/apache/camel/component/http/HttpEndpoint.java index b4caea7..38b9003 100644 --- a/components/camel-http/src/main/java/org/apache/camel/component/http/HttpEndpoint.java +++ b/components/camel-http/src/main/java/org/apache/camel/component/http/HttpEndpoint.java @@ -49,6 +49,8 @@ import org.slf4j.LoggerFactory; @UriEndpoint(scheme = "http,https", title = "HTTP,HTTPS", syntax = "http:httpUri", producerOnly = true, label = "http") public class HttpEndpoint extends DefaultEndpoint implements HeaderFilterStrategyAware { + // Note: all consumer options must be documented with description in annotations so extended components can access the documentation + private static final Logger LOG = LoggerFactory.getLogger(HttpEndpoint.class); private HttpComponent component; @@ -57,7 +59,7 @@ public class HttpEndpoint extends DefaultEndpoint implements HeaderFilterStrateg private HttpConnectionManager httpConnectionManager; private UrlRewrite urlRewrite; - @UriPath @Metadata(required = "true", label = "producer") + @UriPath(label = "producer") @Metadata(required = "true") private URI httpUri; @UriParam private HeaderFilterStrategy headerFilterStrategy = new HttpHeaderFilterStrategy(); @@ -67,11 +69,21 @@ public class HttpEndpoint extends DefaultEndpoint implements HeaderFilterStrateg private boolean throwExceptionOnFailure = true; @UriParam(label = "producer") private boolean bridgeEndpoint; - @UriParam(label = "consumer") + @UriParam(label = "consumer", + description = "Whether or not the consumer should try to find a target consumer by matching the URI prefix if no exact match is found.") private boolean matchOnUriPrefix; @UriParam(defaultValue = "true") private boolean chunked = true; - @UriParam(label = "consumer") + @UriParam(label = "consumer", + description = "Determines whether or not the raw input stream from Jetty is cached or not" + + " (Camel will read the stream into a in memory/overflow to file, Stream caching) cache." + + " By default Camel will cache the Jetty input stream to support reading it multiple times to ensure it Camel" + + " can retrieve all data from the stream. However you can set this option to true when you for example need" + + " to access the raw stream, such as streaming it directly to a file or other persistent store." + + " DefaultHttpBinding will copy the request input stream into a stream cache and put it into message body" + + " if this option is false to support reading the stream multiple times." + + " If you use Jetty to bridge/proxy an endpoint then consider enabling this option to improve performance," + + " in case you do not need to read the message payload multiple times.") private boolean disableStreamCache; @UriParam(label = "producer") private String proxyHost; @@ -81,11 +93,14 @@ public class HttpEndpoint extends DefaultEndpoint implements HeaderFilterStrateg private String authMethodPriority; @UriParam private boolean transferException; - @UriParam(label = "consumer") + @UriParam(label = "consumer", + description = "Specifies whether to enable HTTP TRACE for this Jetty consumer. By default TRACE is turned off.") private boolean traceEnabled; - @UriParam(label = "consumer") + @UriParam(label = "consumer", + description = "Used to only allow consuming if the HttpMethod matches, such as GET/POST/PUT etc. Multiple methods can be specified separated by comma.") private String httpMethodRestrict; - @UriParam(label = "consumer") + @UriParam(label = "consumer", + description = "To use a custom buffer size on the javax.servlet.ServletResponse.") private Integer responseBufferSize; public HttpEndpoint() { @@ -346,7 +361,7 @@ public class HttpEndpoint extends DefaultEndpoint implements HeaderFilterStrateg * By default Camel will cache the Jetty input stream to support reading it multiple times to ensure it Camel * can retrieve all data from the stream. However you can set this option to true when you for example need * to access the raw stream, such as streaming it directly to a file or other persistent store. - * DefaultHttpBinding will copy the request input stream into a stream cache and put it into message bod + * DefaultHttpBinding will copy the request input stream into a stream cache and put it into message body * if this option is false to support reading the stream multiple times. * If you use Jetty to bridge/proxy an endpoint then consider enabling this option to improve performance, * in case you do not need to read the message payload multiple times. http://git-wip-us.apache.org/repos/asf/camel/blob/a4e69971/components/camel-jsch/src/main/java/org/apache/camel/component/scp/ScpConfiguration.java ---------------------------------------------------------------------- diff --git a/components/camel-jsch/src/main/java/org/apache/camel/component/scp/ScpConfiguration.java b/components/camel-jsch/src/main/java/org/apache/camel/component/scp/ScpConfiguration.java index daf452a..d4292d0 100644 --- a/components/camel-jsch/src/main/java/org/apache/camel/component/scp/ScpConfiguration.java +++ b/components/camel-jsch/src/main/java/org/apache/camel/component/scp/ScpConfiguration.java @@ -40,7 +40,7 @@ public class ScpConfiguration extends RemoteFileConfiguration { private String privateKeyFile; @UriParam private String privateKeyFilePassphrase; - @UriParam + @UriParam(enums = "no,yes", defaultValue = "no") private String strictHostKeyChecking; @UriParam private int serverAliveInterval; @@ -80,6 +80,9 @@ public class ScpConfiguration extends RemoteFileConfiguration { return useUserKnownHostsFile; } + /** + * If knownHostFile has not been explicit configured, then use the host file from System.getProperty("user.home") + "/.ssh/known_hosts" + */ public void setUseUserKnownHostsFile(boolean useUserKnownHostsFile) { this.useUserKnownHostsFile = useUserKnownHostsFile; } @@ -104,6 +107,9 @@ public class ScpConfiguration extends RemoteFileConfiguration { return strictHostKeyChecking; } + /** + * Sets whether to use strict host key checking. Possible values are: no, yes + */ public void setStrictHostKeyChecking(String strictHostKeyChecking) { this.strictHostKeyChecking = strictHostKeyChecking; } @@ -124,6 +130,9 @@ public class ScpConfiguration extends RemoteFileConfiguration { return serverAliveCountMax; } + /** + * Allows you to set chmod on the stored file. For example chmod=664. + */ public void setChmod(String chmod) { if (chmod.length() == 3) { for (byte c : chmod.getBytes()) { @@ -158,4 +167,15 @@ public class ScpConfiguration extends RemoteFileConfiguration { public void setCompression(int compression) { this.compression = compression; } + + public boolean isVerboseLogging() { + return verboseLogging; + } + + /** + * To enable verbose logging + */ + public void setVerboseLogging(boolean verboseLogging) { + this.verboseLogging = verboseLogging; + } } http://git-wip-us.apache.org/repos/asf/camel/blob/a4e69971/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/ServletComponent.java ---------------------------------------------------------------------- diff --git a/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/ServletComponent.java b/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/ServletComponent.java index 351a722..e2eba06 100644 --- a/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/ServletComponent.java +++ b/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/ServletComponent.java @@ -156,6 +156,9 @@ public class ServletComponent extends HttpComponent implements RestConsumerFacto return servletName; } + /** + * Default name of servlet to use. The default name is <tt>CamelServlet</tt>. + */ public void setServletName(String servletName) { this.servletName = servletName; } @@ -164,6 +167,9 @@ public class ServletComponent extends HttpComponent implements RestConsumerFacto return httpRegistry; } + /** + * To use a custom {@link org.apache.camel.component.servlet.HttpRegistry}. + */ public void setHttpRegistry(HttpRegistry httpRegistry) { this.httpRegistry = httpRegistry; } http://git-wip-us.apache.org/repos/asf/camel/blob/a4e69971/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/ServletEndpoint.java ---------------------------------------------------------------------- diff --git a/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/ServletEndpoint.java b/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/ServletEndpoint.java index 7c43457..e9a21aa 100644 --- a/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/ServletEndpoint.java +++ b/components/camel-servlet/src/main/java/org/apache/camel/component/servlet/ServletEndpoint.java @@ -34,7 +34,7 @@ import org.apache.commons.httpclient.params.HttpClientParams; syntax = "servlet:servletName", consumerOnly = true, consumerClass = ServletConsumer.class, label = "http") public class ServletEndpoint extends HttpEndpoint { - @UriPath @Metadata(required = "true") + @UriPath(label = "consumer") @Metadata(required = "true") private String servletName; public ServletEndpoint() { http://git-wip-us.apache.org/repos/asf/camel/blob/a4e69971/tooling/apt/src/main/java/org/apache/camel/tools/apt/DocumentationHelper.java ---------------------------------------------------------------------- diff --git a/tooling/apt/src/main/java/org/apache/camel/tools/apt/DocumentationHelper.java b/tooling/apt/src/main/java/org/apache/camel/tools/apt/DocumentationHelper.java index 37e190b..87eaee3 100644 --- a/tooling/apt/src/main/java/org/apache/camel/tools/apt/DocumentationHelper.java +++ b/tooling/apt/src/main/java/org/apache/camel/tools/apt/DocumentationHelper.java @@ -33,22 +33,35 @@ import static org.apache.camel.tools.apt.JsonSchemaHelper.parseJsonSchema; */ public final class DocumentationHelper { - public static String findJavaDoc(String scheme, String extendsScheme, String fieldName) { + public static String findComponentJavaDoc(String scheme, String extendsScheme, String fieldName) { File file = jsonFile(scheme, extendsScheme); if (file != null) { FileInputStream fis = null; try { fis = new FileInputStream(file); String json = loadText(fis); - List<Map<String, String>> rows = parseJsonSchema("properties", json, true); + List<Map<String, String>> rows = parseJsonSchema("componentProperties", json, true); + return getPropertyDescription(rows, fieldName); + } catch (Exception e) { + // ignore + } finally { + IOHelper.close(fis); + } + } - for (Map<String, String> row : rows) { - String name = row.get("name"); - String description = row.get("description"); - if (fieldName.equals(name)) { - return description; - } - } + // not found + return null; + } + + public static String findEndpointJavaDoc(String scheme, String extendsScheme, String fieldName) { + File file = jsonFile(scheme, extendsScheme); + if (file != null) { + FileInputStream fis = null; + try { + fis = new FileInputStream(file); + String json = loadText(fis); + List<Map<String, String>> rows = parseJsonSchema("properties", json, true); + return getPropertyDescription(rows, fieldName); } catch (Exception e) { // ignore } finally { @@ -60,6 +73,23 @@ public final class DocumentationHelper { return null; } + private static String getPropertyDescription(List<Map<String, String>> rows, String name) { + for (Map<String, String> row : rows) { + String description = null; + boolean found = false; + if (row.containsKey("name")) { + found = name.equals(row.get("name")); + } + if (row.containsKey("description")) { + description = row.get("description"); + } + if (found) { + return description; + } + } + return null; + } + private static File jsonFile(String scheme, String extendsScheme) { // TODO: scan components for each component and find component name from extendsScheme // and then find the package name where the json file is http://git-wip-us.apache.org/repos/asf/camel/blob/a4e69971/tooling/apt/src/main/java/org/apache/camel/tools/apt/EndpointAnnotationProcessor.java ---------------------------------------------------------------------- diff --git a/tooling/apt/src/main/java/org/apache/camel/tools/apt/EndpointAnnotationProcessor.java b/tooling/apt/src/main/java/org/apache/camel/tools/apt/EndpointAnnotationProcessor.java index 7f895ed..1531971 100644 --- a/tooling/apt/src/main/java/org/apache/camel/tools/apt/EndpointAnnotationProcessor.java +++ b/tooling/apt/src/main/java/org/apache/camel/tools/apt/EndpointAnnotationProcessor.java @@ -215,8 +215,12 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { buffer.append(","); } buffer.append("\n "); - // as its json we need to sanitize the docs + // either we have the documentation from this apt plugin or we need help to find it from extended component String doc = entry.getDocumentationWithNotes(); + if (Strings.isNullOrEmpty(doc)) { + doc = DocumentationHelper.findComponentJavaDoc(componentModel.getScheme(), componentModel.getExtendsScheme(), entry.getName()); + } + // as its json we need to sanitize the docs doc = sanitizeDescription(doc, false); Boolean required = entry.getRequired() != null ? Boolean.valueOf(entry.getRequired()) : null; String defaultValue = entry.getDefaultValue(); @@ -251,7 +255,12 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { buffer.append(","); } buffer.append("\n "); + // either we have the documentation from this apt plugin or we need help to find it from extended component String doc = entry.getDocumentation(); + if (Strings.isNullOrEmpty(doc)) { + doc = DocumentationHelper.findEndpointJavaDoc(componentModel.getScheme(), componentModel.getExtendsScheme(), entry.getName()); + } + // as its json we need to sanitize the docs doc = sanitizeDescription(doc, false); Boolean required = entry.getRequired() != null ? Boolean.valueOf(entry.getRequired()) : null; String defaultValue = entry.getDefaultValue(); @@ -282,13 +291,12 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { buffer.append(","); } buffer.append("\n "); - // as its json we need to sanitize the docs + // either we have the documentation from this apt plugin or we need help to find it from extended component String doc = entry.getDocumentationWithNotes(); - if (Strings.isNullOrEmpty(doc)) { - doc = DocumentationHelper.findJavaDoc(componentModel.getScheme(), componentModel.getExtendsScheme(), entry.getName()); + doc = DocumentationHelper.findEndpointJavaDoc(componentModel.getScheme(), componentModel.getExtendsScheme(), entry.getName()); } - + // as its json we need to sanitize the docs doc = sanitizeDescription(doc, false); Boolean required = entry.getRequired() != null ? Boolean.valueOf(entry.getRequired()) : null; String defaultValue = entry.getDefaultValue(); @@ -537,6 +545,9 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { String defaultValueNote = path.defaultValueNote(); String required = metadata != null ? metadata.required() : null; String label = path.label(); + if (Strings.isNullOrEmpty(label) && metadata != null) { + label = metadata.label(); + } TypeMirror fieldType = fieldElement.asType(); String fieldTypeName = fieldType.toString(); @@ -592,6 +603,9 @@ public class EndpointAnnotationProcessor extends AbstractAnnotationProcessor { String defaultValueNote = param.defaultValueNote(); String required = metadata != null ? metadata.required() : null; String label = param.label(); + if (Strings.isNullOrEmpty(label) && metadata != null) { + label = metadata.label(); + } // if the field type is a nested parameter then iterate through its fields TypeMirror fieldType = fieldElement.asType();
