001/*
002 * The contents of this file are subject to the terms of the Common Development and
003 * Distribution License (the License). You may not use this file except in compliance with the
004 * License.
005 *
006 * You can obtain a copy of the License at legal/CDDLv1.0.txt. See the License for the
007 * specific language governing permission and limitations under the License.
008 *
009 * When distributing Covered Software, include this CDDL Header Notice in each file and include
010 * the License file at legal/CDDLv1.0.txt. If applicable, add the following below the CDDL
011 * Header, with the fields enclosed by brackets [] replaced by your own identifying
012 * information: "Portions copyright [year] [name of copyright owner]".
013 *
014 * Copyright 2014 ForgeRock AS.
015 */
016
017package org.forgerock.openig.http;
018
019import java.security.cert.X509Certificate;
020import java.util.List;
021
022/**
023 * ClientInfo gives easy access to client-related information that are available into the request.
024 * Supported data includes:
025 * <ul>
026 *     <li>Remote IP address or hostname</li>
027 *     <li>Remote port</li>
028 *     <li>Username</li>
029 *     <li>Client provided X509 certificates</li>
030 *     <li>User-Agent information</li>
031 * </ul>
032 */
033public interface ClientInfo {
034
035    /**
036     * Returns the login of the user making this request or {@code null} if not known.
037     *
038     * @return the login of the user making this request or {@code null} if not known.
039     * @see javax.servlet.http.HttpServletRequest#getRemoteUser()
040     */
041    String getRemoteUser();
042
043    /**
044     * Returns the IP address of the client (or last proxy) that sent the request.
045     *
046     * @return the IP address of the client (or last proxy) that sent the request.
047     * @see javax.servlet.ServletRequest#getRemoteAddr()
048     */
049    String getRemoteAddress();
050
051    /**
052     * Returns the fully qualified name of the client (or last proxy) that sent the request.
053     *
054     * @return the fully qualified name of the client (or last proxy) that sent the request.
055     * @see javax.servlet.ServletRequest#getRemoteHost()
056     */
057    String getRemoteHost();
058
059    /**
060     * Returns the source port of the client (or last proxy) that sent the request.
061     *
062     * @return the source port of the client (or last proxy) that sent the request.
063     * @see javax.servlet.ServletRequest#getRemotePort()
064     */
065    int getRemotePort();
066
067    /**
068     * Returns the list (possibly empty) of X509 certificate(s) provided by the client.
069     * If no certificates are available, an empty list is returned.
070     *
071     * @return the list (possibly empty) of X509 certificate(s) provided by the client.
072     */
073    List<X509Certificate> getCertificates();
074
075    /**
076     * Returns the value of the {@literal User-Agent} HTTP Header (if any, returns {@code null} otherwise).
077     *
078     * @return the value of the {@literal User-Agent} HTTP Header (if any, returns {@code null} otherwise).
079     */
080    String getUserAgent();
081}