Chapter 39. Component Interface

To implement a Apache Camel component, you must implement the org.apache.camel.Component interface. An instance of Component type provides the entry point into a custom component. That is, all of the other objects in a component are ultimately accessible through the Component instance. Figure 39.1, “Component Inheritance Hierarchy” shows the relevant Java interfaces and classes that make up the Component inheritance hierarchy.

Figure 39.1. Component Inheritance Hierarchy

Example 39.1, “Component Interface” shows the definition of the org.apache.camel.Component interface.

package org.apache.camel;

public interface Component {
    CamelContext getCamelContext();
    void setCamelContext(CamelContext context);

    Endpoint createEndpoint(String uri) throws Exception;
}

The Component interface defines the following methods:

You implement a new component by extending the org.apache.camel.impl.DefaultComponent class, which provides some standard functionality and default implementations for some of the methods. In particular, the DefaultComponent class provides support for URI parsing and for creating a scheduled executor (which is used for the scheduled poll pattern).

The createEndpoint(String uri) method defined in the base Component interface takes a complete, unparsed endpoint URI as its sole argument. The DefaultComponent class, on the other hand, defines a three-argument version of the createEndpoint() method with the following signature:

protected abstract Endpoint createEndpoint(
    String uri,
    String remaining,
    Map parameters
)
throws Exception;

uri is the original, unparsed URI; remaining is the part of the URI that remains after stripping off the component prefix at the start and cutting off the query options at the end; and parameters contains the parsed query options. It is this version of the createEndpoint() method that you must override when inheriting from DefaultComponent. This has the advantage that the endpoint URI is already parsed for you.

The following sample endpoint URI for the file component shows how URI parsing works in practice:

file:///tmp/messages/foo?delete=true&moveNamePostfix=.old

For this URI, the following arguments are passed to the three-argument version of createEndpoint():

By default, the parameters extracted from the URI query options are injected on the endpoint’s bean properties. The DefaultComponent class automatically injects the parameters for you.

For example, if you want to define a custom endpoint that supports two URI query options: delete and moveNamePostfix. All you must do is define the corresponding bean methods (getters and setters) in the endpoint class:

public class FileEndpoint extends ScheduledPollEndpoint {
    ...
    public boolean isDelete() {
        return delete;
    }
    public void setDelete(boolean delete) {
        this.delete = delete;
    }
    ...
    public String getMoveNamePostfix() {
        return moveNamePostfix;
    }
    public void setMoveNamePostfix(String moveNamePostfix) {
        this.moveNamePostfix = moveNamePostfix;
    }
}

It is also possible to inject URI query options into consumer parameters. For details, see the section called “Consumer parameter injection”.

If there are no parameters defined on your Endpoint class, you can optimize the process of endpoint creation by disabling endpoint parameter injection. To disable parameter injection on endpoints, override the useIntrospectionOnEndpoint() method and implement it to return false, as follows:

protected boolean useIntrospectionOnEndpoint() {
  return false;
}

The scheduled executor is used in the scheduled poll pattern, where it is responsible for driving the periodic polling of a consumer endpoint (a scheduled executor is effectively a thread pool implementation).

To instantiate a scheduled executor service, use the ExecutorServiceStrategy object that is returned by the CamelContext.getExecutorServiceStrategy() method. For details of the Apache Camel threading model, see Section 2.8, “Threading Model”.

If you want to validate the URI before creating an endpoint instance, you can override the validateURI() method from the DefaultComponent class, which has the following signature:

protected void validateURI(String uri,
                           String path,
                           Map parameters)
   throws ResolveEndpointFailedException;

If the supplied URI does not have the required format, the implementation of validateURI() should throw the org.apache.camel.ResolveEndpointFailedException exception.

Example 39.2, “Implementation of createEndpoint()” outlines how to implement the DefaultComponent.createEndpoint() method, which is responsible for creating endpoint instances on demand.

public class CustomComponent extends DefaultComponent { 1
    ...
    protected Endpoint createEndpoint(String uri, String remaining, Map parameters) throws Exception { 2
        CustomEndpoint result = new CustomEndpoint(uri, this); 3
        // ...
        return result;
    }
}

Example 39.3, “FileComponent Implementation” shows a sample implementation of a FileComponent class.

package org.apache.camel.component.file;

import org.apache.camel.CamelContext;
import org.apache.camel.Endpoint;
import org.apache.camel.impl.DefaultComponent;

import java.io.File;
import java.util.Map;

public class FileComponent extends DefaultComponent {
    public static final String HEADER_FILE_NAME = "org.apache.camel.file.name";

    public FileComponent() { 1
    }

    public FileComponent(CamelContext context) { 2
        super(context);
    }

    protected Endpoint createEndpoint(String uri, String remaining, Map parameters) throws Exception { 3
        File file = new File(remaining);
        FileEndpoint result = new FileEndpoint(file, uri, this);
        return result;
    }
}

SynchronizationRouteAware interface allows you to have callbacks before and after the exchange has been routed.