Java API Hooks

tCell.io provides API hooks in order to enable application to pass data to the tCell.io service. This is particularly useful when you have custom code, and are not using a framework that the tCell agent is aware of.

API hooks are empty methods that are called at the appropriate points in your application. When tCell agent is installed with your application, then it will populate the method to send the data to the tCell.io service. When tCell agent is not present, then the method will do nothing. This makes it very convenient for development whom may not want tCell running.

tCell API hooks support the following situations:

  • sending a login event
  • setting the current userid
  • setting the current sessionid

The jar file can be found in the tcell-jvmagent-*.tar.gz or tcell-jvmagent-*.zip as tcellagent-hooks-*.jar

 

Login Event

In order to send a login event, at the time of login, once you've determined if the login is successful or not, you should call the method io.tcellagent.hooks.v1.login.LoginReporter.registerLoginEvent().

Settings

In some cases, tCell.io will not be able to get your sessionid or userid for http requests. In such cases, you can set them yourself at the earliest point these values are known. This is done by the following methods, respectively:

io.tcellagent.hooks.v1.TCellSettings.setSessionId(String sid)

io.tcellagent.hooks.v1.TCellSettings.setUserId(String userName).

 

API Documentation

public final class io.tcellagent.hooks.v1.login.LoginReporter extends java.lang.Object

 

public static void registerLoginEvent(LoginStatus event,
                                      java.lang.String session,
                                      java.lang.String userAgent,
                                      java.lang.String referrer,
                                      java.lang.String remoteAddr,
                                      java.lang.String[] headerKeys,
                                      java.lang.String userId,
                                      java.lang.String documentUri)

 

public static void registerLoginEvent(LoginStatus event,
                                      java.lang.String session,
                                      java.lang.String userAgent,
                                      java.lang.String referrer,
                                      java.lang.String remoteAddr,
                                      java.lang.String[] headerKeys,
                                      java.lang.String userId,
                                      java.lang.String documentUri,
                                      java.lang.Boolean userValid)


event - type of event. See LoginStatus
session - String for the sessionId. See code example below.
userAgent - Value from Http Header. For example, from req.getHeader("User-Agent")
referrer - Value from Http Header. For example, from  req.getHeader("Referer")
remoteAddr - The IP from the client. (at times could be X-Forwarded-For)
headerKeys - an array of header keys. For example, from req.getHeaderNames()
usedId - String for the userid being used.
documentUri - Current URI. For example, req.getRequestURI()
validUser - true or false depending on if the user is valid/known or not.


java.lang.Object
java.lang.Enum<LoginStatus>
io.tcellagent.hooks.v1.login.LoginStatus

public static final LoginStatus LOGIN_SUCCESS
public static final LoginStatus LOGIN_FAILURE


public final class io.tcellagent.hooks.v1.TCellSettings

public static void setUserId( String userId )
userId - String value of user id, e.g 'joe.user@customer.com'.

public static void setSessionId( String sessionId )
sessionId - String of sessionId value. Note that this value will be securely hashed before sending to the tCell service.

Example Login:

public class LoginServlet extends HttpServlet {
  
    @Override
    protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
        String userId = req.getParameter("customUserIdField");
        String password = req.getParameter("customPasswordField");
        boolean success = false;
        boolean validUser = isUserValid(userId);
        if (validUser) {
            success = login(userId, password);
        }
        LoginStatus status = success ? LoginStatus.LOGIN_SUCCESS : LoginStatus.LOGIN_FAILURE;
        HttpSession session = req.getSession(false);
        String sessionId = session != null ? session.getId() : null;
        Enumeration < String > headerNames = req.getHeaderNames();
        ArrayList < String > names = new ArrayList < > ();
        while (headerNames.hasMoreElements()) {
            names.add(headerNames.nextElement());
        }
        LoginReporter.registerLoginEvent(status,
            sessionId,
            req.getHeader("User-Agent"),
            req.getHeader("Referer"),
            req.getRemoteAddr(), // Note: the real client IP may be in a header if using proxy!
            names.toArray(new String[0]),
            userId,
            req.getRequestURI(),
            validUser);
        resp.setStatus(success ? 200 : 401);
    }
 
    public boolean isUserValid(String userId) {
        return "user".equals(userId);
    }
 
    public boolean login(String userId, String password) {
        return "user".equals(userId) && "password".equals(password);
    }
}
 

 

Example Session Filter

public class MySessionFilter implements Filter {

public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) 
throws IOException, ServletException {

...
  io.tcellagent.hooks.v1.TCellSettings.setUserId( <User Id> );
  io.tcellagent.hooks.v1.TCellSettings.setSessionId( <session ID> );
  doFilter(request, response, chain);
}
}

 
Have more questions? Submit a request

Comments