Creating Custom
Plugins

package com.example.plugins;

import org.webharvest.plugin.AbstractPlugin;
import org.webharvest.plugin.annotations.CorePlugin;
import org.webharvest.plugin.PluginConfiguration;
import org.webharvest.plugin.PluginMetadata;
import org.webharvest.plugin.exceptions.PluginException;
import org.webharvest.runtime.DynamicScopeContext;
import org.webharvest.runtime.variables.Variable;
import org.webharvest.runtime.variables.NodeVariable;
import java.util.Base64;

/**
 * Encodes text to Base64.
 * 
 * Usage:
 * <base64 charset="UTF-8">text to encode</base64>
 */
@CorePlugin(elementName = "base64")
public class Base64Plugin extends AbstractPlugin {
    
    private String charset = "UTF-8";
    
    @Override
    protected void doInitialize(PluginConfiguration config) throws PluginException {
        // Get optional charset attribute
        this.charset = config.getAttribute("charset", "UTF-8");
    }
    
    @Override
    protected void doValidateConfiguration(PluginConfiguration config) {
        // Validate charset if provided
        String charsetAttr = config.getAttribute("charset");
        if (charsetAttr != null && !isValidCharset(charsetAttr)) {
            throw new PluginValidationException(
                "Invalid charset: " + charsetAttr
            );
        }
    }
    
    @Override
    protected Variable doExecute(DynamicScopeContext context) 
            throws InterruptedException {
        // Get body content
        Variable bodyResult = executeBody(context);
        String input = bodyResult.toString();
        
        // Encode to Base64
        byte[] encoded = Base64.getEncoder().encode(
            input.getBytes(charset)
        );
        
        return new NodeVariable(new String(encoded));
    }
    
    @Override
    public PluginMetadata getMetadata() {
        return new PluginMetadata() {
            @Override
            public String getName() { return "base64"; }
            
            @Override
            public String getDescription() { 
                return "Encodes text to Base64"; 
            }
            
            @Override
            public String getVersion() { return "1.0.0"; }
        };
    }
    
    private boolean isValidCharset(String charset) {
        try {
            java.nio.charset.Charset.forName(charset);
            return true;
        } catch (Exception e) {
            return false;
        }
    }
}

<def var="encoded">
    <base64 charset="UTF-8">
        Hello, WebHarvest!
    </base64>
</def>

<!-- Result: SGVsbG8sIFdlYkhhcnZlc3Qh -->

# Copy JAR to lib directory
cp my-plugin.jar $WEBHARVEST_HOME/lib/

# Or run with classpath
java -cp webharvest-core.jar:my-plugin.jar \
    org.webharvest.Main config.xml

# Scan custom packages
java -Dwebharvest.plugin.packages=com.example.plugins,com.mycompany \
     -jar webharvest-cli.jar config.xml

import org.webharvest.plugin.scanner.PluginPackageScanner;
import org.webharvest.definition.CorePluginRegistry;

CorePluginRegistry registry = CorePluginRegistry.getInstance();
PluginPackageScanner scanner = new PluginPackageScanner(registry);

// Scan your custom packages
scanner.scanPackages("com.example.plugins", "com.mycompany.webharvest");

webharvest-myextension/
├── pom.xml
├── README.md
└── src/
    └── main/
        ├── java/
        │   └── org/webharvest/plugin/myext/
        │       ├── MyExtPlugin.java
        │       └── MyExtException.java
        └── resources/
            └── META-INF/
                └── services/
                    └── org.webharvest.plugin.Plugin

<project>
    <groupId>org.webharvest</groupId>
    <artifactId>webharvest-myextension</artifactId>
    <version>2.2.0</version>
    
    <dependencies>
        <!-- Core dependency -->
        <dependency>
            <groupId>org.webharvest</groupId>
            <artifactId>webharvest-core</artifactId>
            <version>2.2.0</version>
            <scope>provided</scope>
        </dependency>
        
        <!-- Your heavy dependency -->
        <dependency>
            <groupId>com.example</groupId>
            <artifactId>heavy-library</artifactId>
            <version>1.0.0</version>
        </dependency>
    </dependencies>
</project>

import org.junit.Test;
import static org.junit.Assert.*;

public class Base64PluginTest {
    
    @Test
    public void shouldEncodeText() throws Exception {
        // Create plugin
        Base64Plugin plugin = new Base64Plugin();
        
        // Create mock configuration
        PluginConfiguration config = new MockPluginConfiguration();
        plugin.initialize(config);
        
        // Create mock context with body
        DynamicScopeContext context = createContextWithBody("Hello");
        
        // Execute
        Variable result = plugin.execute(context);
        
        // Verify
        assertEquals("SGVsbG8=", result.toString());
    }
}

Source: webharvest-core/src/main/java/org/webharvest/plugin/core/HttpPlugin.java

Features to learn:
• Attribute handling (url, method, timeout)
• Child element processing (headers, params)
• Resource management (HTTP connections)
• Error handling (network failures)
• Token tracking (HTTP_REQUEST, HTTP_BYTES)

Source: webharvest-core/src/main/java/org/webharvest/plugin/core/TemplatePlugin.java

Features to learn:
• Variable substitution
• Context manipulation
• Body execution
• String processing

Source: webharvest-mail/src/main/java/org/webharvest/plugin/mail/MailPlugin.java

Features to learn:
• External dependencies (JavaMail)
• Separate Maven module
• Complex configuration
• Resource cleanup