Java

Getting started

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:

1
io.tcellagent.hooks.v1.login.LoginReporter.registerLoginEvent()

Settings

In some cases, tCell 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:

1
io.tcellagent.hooks.v1.TCellSettings.setSessionId(String sid)
2
3
io.tcellagent.hooks.v1.TCellSettings.setUserId(String userName).

API Documentation

1
public final class io.tcellagent.hooks.v1.login.LoginReporter extends java.lang.Object
1
public static void registerLoginEvent(LoginStatus event,
2
java.lang.String session,
3
java.lang.String userAgent,
4
java.lang.String referrer,
5
java.lang.String remoteAddr,
6
java.lang.String[] headerKeys,
7
java.lang.String userId,
8
java.lang.String documentUri)
1
public static void registerLoginEvent(LoginStatus event,
2
java.lang.String session,
3
java.lang.String userAgent,
4
java.lang.String referrer,
5
java.lang.String remoteAddr,
6
java.lang.String[] headerKeys,
7
java.lang.String userId,
8
java.lang.String documentUri,
9
java.lang.Boolean userValid)
1
public static void registerLoginEvent(LoginStatus event,
2
java.lang.String session,
3
java.lang.String userAgent,
4
java.lang.String referrer,
5
java.lang.String remoteAddr,
6
java.lang.String[] headerKeys,
7
java.lang.String userId,
8
java.lang.String documentUri,
9
java.lang.Boolean userValid,
10
java.lang.String password)

Detailed parameter information is below

ParameterDetails
eventtype of event. See LoginStatus
sessionString for the sessionId. See code example below
userAgentValue from Http Header. For example, from req.getHeader("User-Agent")
referrerValue from Http Header. For example, from req.getHeader("Referer")
remoteAddrThe IP from the client. (at times could be X-Forwarded-For)
headerKeysan array of header keys. For example, from req.getHeaderNames()
userIdString for the userid being used.
passwordPassword of failed/successful login.

LoginStatus

1
java.lang.Object
2
java.lang.Enum<LoginStatus>
3
io.tcellagent.hooks.v1.login.LoginStatus
4
5
public static final LoginStatus LOGIN_SUCCESS
6
public static final LoginStatus LOGIN_FAILURE
1
public final class io.tcellagent.hooks.v1.TCellSettings
2
3
public static void setUserId( String userId )
4
userId - String value of user id, e.g 'joe.user@customer.com'.
5
6
public static void setSessionId( String sessionId )
7
sessionId - String of sessionId value. Note that this value will be securely hashed before sending to the tCell service.

Example Login

1
public class LoginServlet extends HttpServlet {
2
3
@Override
4
protected void doPost(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException {
5
String userId = req.getParameter("customUserIdField");
6
String password = req.getParameter("customPasswordField");
7
boolean success = false;
8
boolean validUser = isUserValid(userId);
9
if (validUser) {
10
success = login(userId, password);
11
}
12
LoginStatus status = success ? LoginStatus.LOGIN_SUCCESS : LoginStatus.LOGIN_FAILURE;
13
HttpSession session = req.getSession(false);
14
String sessionId = session != null ? session.getId() : null;
15
Enumeration < String > headerNames = req.getHeaderNames();
16
ArrayList < String > names = new ArrayList < > ();
17
while (headerNames.hasMoreElements()) {
18
names.add(headerNames.nextElement());
19
}
20
LoginReporter.registerLoginEvent(status,
21
sessionId,
22
req.getHeader("User-Agent"),
23
req.getHeader("Referer"),
24
req.getRemoteAddr(), // Note: the real client IP may be in a header if using proxy!
25
names.toArray(new String[0]),
26
userId,
27
req.getRequestURI(),
28
validUser,
29
password);
30
resp.setStatus(success ? 200 : 401);
31
}
32
33
public boolean isUserValid(String userId) {
34
return "user".equals(userId);
35
}
36
37
public boolean login(String userId, String password) {
38
return "user".equals(userId) && "password".equals(password);
39
}
40
}
1
Example Session Filter
2
3
public class MySessionFilter implements Filter {
4
5
public void doFilter(ServletRequest request, ServletResponse response, FilterChain chain) throws IOException, ServletException {
6
7
...
8
io.tcellagent.hooks.v1.TCellSettings.setUserId( <User Id> );
9
io.tcellagent.hooks.v1.TCellSettings.setSessionId( <session ID> );
10
doFilter(request, response, chain);
11
}
12
}