Skip to main content
Version: 4.6.1-saas

Installation and Initialization

This guide explains the installation and initialization process for the NetFUNNEL Java agent.

Step 1: Install Library​

Gradle (Kotlin DSL)​

Add the following dependencies to build.gradle.kts:

implementation(files("libs/netfunnel-agent.jar"))
implementation("com.google.code.gson:gson:2.9.1")
implementation("com.fasterxml.jackson.module:jackson-module-kotlin")

Gradle (Groovy DSL)​

Add the following dependencies to build.gradle:

implementation files('libs/netfunnel-agent.jar')
implementation 'com.google.code.gson:gson:2.9.1'
// When using Java
implementation 'com.fasterxml.jackson.module:jackson-module-kotlin'

Maven​

Add the following dependencies to pom.xml:

<dependency>
    <groupId>com.google.code.gson</groupId>
    <artifactId>gson</artifactId>
    <version>2.9.1</version>
</dependency>
<dependency>
    <groupId>com.fasterxml.jackson.module</groupId>
    <artifactId>jackson-module-kotlin</artifactId>
    <version>2.15.2</version>
</dependency>

Add the netfunnel-agent.jar file to the libs folder and add the following configuration:

<dependency>
    <groupId>com.stclab</groupId>
    <artifactId>netfunnel-agent</artifactId>
    <version>4.0.1</version>
    <scope>system</scope>
    <systemPath>${project.basedir}/libs/netfunnel-agent.jar</systemPath>
</dependency>

Step 2: Get Client ID and Secret Key​

  1. Go to NetFUNNEL Console
  2. Click the profile icon in the top right corner
  3. Select the Integration Credentials menu
  4. Copy Client ID and Secret Key
Client ID and Secret Key Location

You can find them in the Integration Credentials menu after clicking the profile icon in the top right corner of the console screen.

Step 3: Apply Interceptor or Filter​

Select and apply only one of Interceptor or Filter according to your project structure. Both methods provide the same NetFUNNEL queue control functionality, so there is no need to implement them redundantly.

Interceptor Application Method​

1. Create Interceptor​

Write the following code in the Interceptor that receives server requests first:

import com.stclab.Netfunnel;
import com.stclab.servlet.NetFunnelServletService;
import com.stclab.utils.NetFunnelInitialize;
import org.springframework.stereotype.Component;
import org.springframework.web.servlet.HandlerInterceptor;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;

@Component
public class NetFunnelInterceptor implements HandlerInterceptor {
    @Override
    public boolean preHandle(HttpServletRequest request, HttpServletResponse response, Object handler) throws Exception {
        NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
            .clientId("{{CLIENT_ID}}")  // Client ID obtained in Step 2
            .secretKey("{{SECRET_KEY}}")  // Secret Key obtained in Step 2
            .build();
        Netfunnel netfunnel = new Netfunnel(config, new NetFunnelServletService(request, response), null, null);
        return netfunnel.run();
    }
}

2. Register Interceptor​

Register the created interceptor by overriding the addInterceptors method of WebMvcConfigurer:

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.context.annotation.Configuration;
import org.springframework.web.servlet.config.annotation.InterceptorRegistry;
import org.springframework.web.servlet.config.annotation.WebMvcConfigurer;

@Configuration
public class WebConfig implements WebMvcConfigurer {
    private final NetFunnelInterceptor netFunnelInterceptor;
    
    @Autowired
    public WebConfig(NetFunnelInterceptor netFunnelInterceptor) {
        this.netFunnelInterceptor = netFunnelInterceptor;
    }
    
    @Override
    public void addInterceptors(InterceptorRegistry registry) {
        registry.addInterceptor(netFunnelInterceptor)
                .addPathPatterns("/**");
    }
}

Filter Application Method​

1. Create Filter​

Write the following code in the Filter that receives server requests first:

import com.stclab.Netfunnel;
import com.stclab.servlet.NetFunnelServletService;
import com.stclab.utils.NetFunnelInitialize;

import javax.servlet.*;
import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import java.io.IOException;

public class NetFunnelFilter implements Filter {
    @Override
    public void doFilter(ServletRequest servletRequest, ServletResponse servletResponse, FilterChain chain)
            throws IOException, ServletException {
        HttpServletRequest request = (HttpServletRequest) servletRequest;
        HttpServletResponse response = (HttpServletResponse) servletResponse;
        NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
            .clientId("{{CLIENT_ID}}")  // Client ID obtained in Step 2
            .secretKey("{{SECRET_KEY}}")  // Secret Key obtained in Step 2
            .build();
        Netfunnel netfunnel = new Netfunnel(config, new NetFunnelServletService(request, response), null, null);
        if (!netfunnel.run()) {
            return;
        }
        chain.doFilter(servletRequest, servletResponse);
    }
}

2. Register Filter​

Register the created Filter as a bean:

import org.springframework.boot.web.servlet.FilterRegistrationBean;
import org.springframework.context.annotation.Bean;
import org.springframework.context.annotation.Configuration;

import javax.servlet.Filter;

@Configuration
public class FilterConfig {
    @Bean
    public FilterRegistrationBean<Filter> filterRegistrationBean() {
        FilterRegistrationBean<Filter> registration = new FilterRegistrationBean<>();
        registration.setFilter(new NetFunnelFilter());
        registration.addUrlPatterns("/*");
        registration.setOrder(1);
        return registration;
    }
}

Step 4: Initialization Settings​

For detailed information about initialization settings, refer to the Initialization Settings document.

Basic Initialization Example​

NetFunnelInitialize config = NetFunnelInitialize.Companion.builder()
    .clientId("{{CLIENT_ID}}")
    .secretKey("{{SECRET_KEY}}")
    .build();

Step 5: Verify Installation​

To verify that the agent is installed correctly, check the following:

  1. Dependency Check: Verify that netfunnel-agent.jar, gson, and jackson-module-kotlin are correctly added
  2. Initialization Success: No errors should occur when starting the server
  3. Interceptor/Filter Application: Verify that requests are processed correctly

Troubleshooting​

Library Installation Failure:

  • Verify that the netfunnel-agent.jar file is in the libs folder
  • Verify that Gradle/Maven dependencies are correctly added

Initialization Failure:

  • Verify that clientId and secretKey are correctly set
  • Verify that they are not empty strings

Interceptor/Filter Not Working:

  • Verify that Interceptor/Filter is correctly registered
  • Verify that addPathPatterns is correctly set

Next Steps​