# Connector API

## Development steps

1. Create project using the template
2. Define connector specification
3. Implement custom transport
4. Build, test and package
5. Deploy

## Explaining each step <a href="#explaining-each-step" id="explaining-each-step"></a>

### Step 1: Create project using the template   <a href="#step-1-create-the-destination-using-the-template" id="step-1-create-the-destination-using-the-template"></a>

We have provided a project template project to quick start development. The project can be found [here](https://gitlab.com/joule-platform/fractalworks-project-templates). Clone the template project and copy relevant code and structure to your own project

<pre class="language-bash"><code class="lang-bash"><strong>git clone git@gitlab.com:joule-platform/fractalworks-project-templates.git
</strong></code></pre>

{% hint style="info" %}
Joule uses Gradle to manage Java dependencies. To add dependencies for your connector, manage them in the `build.gradle` file inside your connector's directory.
{% endhint %}

### Step 2: Define connector specification <a href="#step-1-create-the-destination-using-the-template" id="step-1-create-the-destination-using-the-template"></a>

For components to be defined using the Joule DSL a specification class is required. Joule provides a `AbstractTransportSpecification` class that is to be extended for your implementation. This class provides core attributes that support a number of features such as:

* Batching
* Formatting
* Parsing Threads

#### Publisher Example

```java
@JsonRootName(value = "templatePublisher")
public class TemplatePublisherSpecification extends AbstractTransportSpecification {

    private String someField;

    /**
     * Default and required
     */
    public TemplatePublisherSpecification() {
        super();
    }

    /**
     * Default and required
     */
    public TemplatePublisherSpecification(String name) {
        super(name);
    }
    
    @JsonProperty(value = "some field", required = true)
    public void setSomeField(String someField) {
        this.someField = someField;
    }

    @Override
    public void validate() throws InvalidSpecificationException {
        super.validate();
        // TODO: Add validation logic based upon required fields
        if (someField == null || someField.isEmpty()) {
            throw new InvalidSpecificationException("someField must be provided.");
        }
    }
    
    @JsonIgnore
    @Override
    public Class<? extends Transport> getComponentClass() {
        // TODO: Change to your transport class
        return TemplatePublisherTransport.class;
    }
}
```

There is an option to create a specification builder in the event of programmactically. See the `TemplatePublisherSpecificationBuilder` example class for a reference implementation.

For Joule to load and initialised the component the specifications need to be defined within the `plugins.properties` file under the `META-INF/services` directory

#### Example

```properties
# Change and add lines for your specification classes
com.fractalworks.streams.examples.transport.TemplatePublisherSpecification
```

### Step 3: Implement  custom transport <a href="#step-1-create-the-destination-using-the-template" id="step-1-create-the-destination-using-the-template"></a>

Now we can move on to building the transport class that will either consume or publish events.&#x20;

#### Publisher Example

Publisher has two key  methods to implement;  initialise and publish.

```java
// Some code
public class TemplatePublisherTransport extends AbstractPublisherTransport {

    private String someField;

    public TemplatePublisherTransport() {
        super();
        logger = LoggerFactory.getLogger(TemplatePublisherTransport.class);
    }

    public TemplatePublisherTransport(TemplatePublisherSpecification specification) {
        super(specification);
        logger = LoggerFactory.getLogger(TemplatePublisherTransport.class);
        someField = specification.getSomeField();
    }

    @Override
    public void initialize() {
        super.initialize();
        // TODO: Add custom transport initialisation code
    }

    @Override
    public void publish(Collection<StreamEvent> events) {
        // TODO: Add custom transport logic to transmit events
    }
}
```

#### Consumer Example <a href="#step-1-create-the-destination-using-the-template" id="step-1-create-the-destination-using-the-template"></a>

Consumer has two key  methods to implement;  initialise and start.

```java
public class TemplateConsumerTransport extends AbstractConsumerTransport {

    public TemplateConsumerTransport() {
        super();
        logger = LoggerFactory.getLogger(TemplateConsumerTransport.class);
    }

    public TemplateConsumerTransport(TemplateConsumerSpecification specification) {
        super(specification);
        logger = LoggerFactory.getLogger(TemplateConsumerTransport.class);
    }

    @Override
    public void initialize() {
        super.initialize();
        // TODO: Add custom transport initialisation code
    }
    

    @Override
    public void start() {
        super.start();
        // TODO: Add custom transport consumer code
    }
}
```

### Step 4: Build, test and package <a href="#step-1-create-the-destination-using-the-template" id="step-1-create-the-destination-using-the-template"></a>

The template project provides basic JUnit test to validate DSL. The project will execute these tests during the gradle build cycle and deploy to your local maven repository.&#x20;

```
gradle build publishToMavenLocal
```

### Step 5: Deploy <a href="#step-1-create-the-destination-using-the-template" id="step-1-create-the-destination-using-the-template"></a>

Once your package has been successfully created you are ready to deploy to a Joule project. The resulting jar artefact needs to be placed in to the `userlibs` directory in your Joule projects directory. See provided examples [documentation](https://docs.fractalworks.io/joule/use-case-examples/overview) for further directions.

```bash
cp build/libs/<your-connector>.jar <location>/userlibs
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.fractalworks.io/joule/developer-guides/builder-sdk/connector-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.