linktool.java

一个用于java web页面开发的开源包

     *
     * Example:<br>
     * <code>&lt;a href='$link.setAbsolute("/templates/login/index.vm")'&gt;Login Page&lt;/a&gt;</code><br>
     * produces something like<br/>
     * <code>&lt;a href="http://myserver.net/myapp/templates/login/index.vm"&gt;Login Page&lt;/a&gt;</code><br>
     * and<br>
     * <code>&lt;a href='$link.setAbsolute("http://theirserver.com/index.jsp")'&gt;Their, Inc.&lt;/a&gt;</code><br>
     * produces something like<br/>
     * <code>&lt;a href="http://theirserver.net/index.jsp"&gt;Their, Inc.&lt;/a&gt;</code><br>
     *
     * @param uri A context-relative URI reference or absolute URL.
     * @return a new instance of LinkTool with the specified URI
     * @since VelocityTools 1.3
     */
    public LinkTool setAbsolute(String uri)
    {
        // if they're creating a url for a separate site
        if (uri.startsWith("http"))
        {
            // just set the URI
            return setURI(uri);
        }
        else
        {
            // otherwise, prepend this webapp's context url
            String fullCtx = getContextURL();
            if (uri.startsWith("/"))
            {
                return copyWith(fullCtx + uri);
            }
            else
            {
                return copyWith(fullCtx + '/' + uri);
            }
        }
    }

    /**
     * Convenience method equivalent to {@link #setAbsolute}.
     * @since VelocityTools 1.3
     */
    public LinkTool absolute(String uri)
    {
        return setAbsolute(uri);
    }


    /**
     * <p>Returns a copy of the link with the given URI reference set.
     * No conversions are applied to the given URI reference. The URI
     * reference can be absolute, server-relative, relative and may
     * contain query parameters. This method will overwrite any
     * previous URI reference settings but will copy the query
     * string.</p>
     *
     * @param uri URI reference to set
     *
     * @return a new instance of LinkTool
     */
    public LinkTool setURI(String uri)
    {
        return copyWith(uri);
    }

    /**
     * Convenience method equivalent to {@link #setURI}.
     * @since VelocityTools 1.3
     */
    public LinkTool uri(String uri)
    {
        return setURI(uri);
    }

    /**
     * <p>Returns the current URI of this link as set by the setURI(String),
     * setAbsolute(String) or setRelative(String) methods. Any conversions
     * have been applied. The returned URI reference does not include query
     * data that was added with method addQueryData().</p>
     */
    public String getURI()
    {
        return uri;
    }

    /**
     * Convenience method equivalent to {@link #getURI} to enable
     * all lowercase {@code $link.uri} syntax.
     * @since VelocityTools 1.3
     */
    public String getUri()
    {
        return getURI();
    }


    /**
     * <p>Adds a key=value pair to the query data. This returns a new LinkTool
     * containing both a copy of this LinkTool's query data and the new data.
     * Query data is URL encoded before it is appended.</p>
     *
     * @param key key of new query parameter
     * @param value value of new query parameter
     *
     * @return a new instance of LinkTool
     */
    public LinkTool addQueryData(String key, Object value)
    {
        return copyWith(new QueryPair(key, value));
    }

    /**
     * <p>Adds multiple key=value pairs to the query data.
     * This returns a new LinkTool containing both a copy of
     * this LinkTool's query data and the new data.
     * Query data is URL encoded before it is appended.</p>
     *
     * @param parameters map of new query data keys to values
     * @return a new instance of LinkTool
     * @since VelocityTools 1.3
     */
    public LinkTool addQueryData(Map parameters)
    {
        // don't waste time with null/empty data
        if (parameters == null || parameters.isEmpty())
        {
            return this;
        }
        return copyWith(parameters);
    }

    /**
     * Convenience method equivalent to {@link #addQueryData}.
     * @since VelocityTools 1.3
     */
    public LinkTool param(Object key, Object value)
    {
        return addQueryData(String.valueOf(key), value);
    }

    /**
     * Convenience method equivalent to
     * {@link #addQueryData(Map parameters)}.
     * @since VelocityTools 1.3
     */
    public LinkTool params(Map parameters)
    {
        return addQueryData(parameters);
    }

    /**
     * <p>Returns this link's query data as a url-encoded string e.g.
     * <code>key=value&foo=this+is+encoded</code>.</p>
     */
    public String getQueryData()
    {
        if (queryData != null && !queryData.isEmpty())
        {

            StringBuffer out = new StringBuffer();
            for(int i=0; i < queryData.size(); i++)
            {
                out.append(queryData.get(i));
                if (i+1 < queryData.size())
                {
                    out.append(queryDataDelim);
                }
            }
            return out.toString();
        }
        return null;
    }

    /**
     * Convenience method equivalent to
     * {@link #getQueryData()}.
     * @since VelocityTools 1.3
     */
    public String getParams()
    {
        return getQueryData();
    }


    /**
     * <p>Returns the URI that addresses this web application. E.g.
     * <code>http://myserver.net/myapp</code>. This string does not end
     * with a "/".  Note! This will not represent any URI reference or
     * query data set for this LinkTool.</p>
     */
    public String getContextURL()
    {
        String scheme = request.getScheme();
        int port = request.getServerPort();

        StringBuffer out = new StringBuffer();
        out.append(request.getScheme());
        out.append("://");
        out.append(request.getServerName());
        if ((scheme.equals("http") && port != 80) ||
            (scheme.equals("https") && port != 443))
        {
            out.append(':');
            out.append(port);
        }
        out.append(request.getContextPath());
        return out.toString();
    }


    /**
     * <p>Returns the context path that addresses this web
     * application, e.g. <code>/myapp</code>. This string starts
     * with a "/" but does not end with a "/" Note! This will not
     * represent any URI reference or query data set for this
     * LinkTool.</p>
     */
    public String getContextPath()
    {
        return request.getContextPath();
    }


    /**
     * <p>Retrieves the path for the current request regardless of
     * whether this is a direct request or an include by the
     * RequestDispatcher. Note! This will not
     * represent any URI reference or query data set for this
     * LinkTool.</p>
     *
     * @since VelocityTools 1.3
     */
    public String getRequestPath()
    {
        return ServletUtils.getPath(request);
    }


    /**
     * Returns the full URI of this template without any query data.
     * e.g. <code>http://myserver.net/myapp/stuff/View.vm</code>
     * Note! The returned String will not represent any URI reference
     * or query data set for this LinkTool. A typical application of
     * this method is with the HTML base tag. For example:
     * <code>&lt;base href="$link.baseRef"&gt;</code>
     */
    public String getBaseRef()
    {
        StringBuffer out = new StringBuffer();
        out.append(getContextURL());
        out.append(getRequestPath());
        return out.toString();
    }


    /**
     * This method returns a new "self-referencing" LinkTool for the current
     * request. By default, this is merely a shortcut for calling
     * {@link #relative(String uri)} using the result of
     * {@link #getRequestPath()}.  However, this tool can be configured
     * to return an absolute URI and/or to include the parameters of the
     * current request (in addition to any others set so far).
     *
     * @see #uri(String uri)
     * @see #configure(Map params)
     * @see #setSelfAbsolute(boolean selfAbsolute)
     * @see #setSelfIncludeParameters(boolean selfParams)
     * @since VelocityTools 1.3
     */
    public LinkTool getSelf()
    {
        // first set the uri per configuration
        LinkTool dupe;
        if (this.selfAbsolute)
        {
            dupe = uri(getBaseRef());
        }
        else
        {
            dupe = relative(getRequestPath());
        }

        // then add the params (if so configured)
        if (this.selfParams)
        {
            dupe.params(request.getParameterMap());
        }
        return dupe;
    }


    /**
     * Returns the full URI reference that's been built with this tool,
     * including the query string and anchor, e.g.
     * <code>http://myserver.net/myapp/stuff/View.vm?id=42&type=blue#foo</code>.
     * Typically, it is not necessary to call this method explicitely.
     * Velocity will call the toString() method automatically to obtain
     * a representable version of an object.
     */
    public String toString()
    {
        StringBuffer out = new StringBuffer();

        if (uri != null)
        {
            out.append(uri);
        }

        String query = getQueryData();
        if (query != null)
        {
            // Check if URI already contains query data
            if ( uri == null || uri.indexOf('?') < 0)
            {
                // no query data yet, start query data with '?'
                out.append('?');
            }
            else
            {
                // there is already query data, use data delimiter
                out.append(queryDataDelim);
            }
            out.append(query);
        }

        if (anchor != null)
        {
            out.append('#');
            out.append(encodeURL(anchor));
        }

        String str = out.toString();
        if (str.length() == 0)
        {
            // avoid a potential NPE from Tomcat's response.encodeURL impl
            return str;
        }
        else
        {
            // encode session ID into URL if sessions are used but cookies are
            // not supported
            return response.encodeURL(str);
        }
    }


    /**
     * Use the new URLEncoder.encode() method from java 1.4 if available, else
     * use the old deprecated version.  This method uses reflection to find the appropriate
     * method; if the reflection operations throw exceptions, this will return the url
     * encoded with the old URLEncoder.encode() method.
     *
     * @return String - the encoded url.
     */
    public String encodeURL(String url)
    {
        /* first try encoding with new 1.4 method */
        if (encode != null)
        {
            try
            {
                Object[] args =
                    new Object[] { url, this.response.getCharacterEncoding() };
                return (String)encode.invoke(null, args);
            }
            catch (IllegalAccessException e)
            {
                // don't keep trying if we get one of these
                encode = null;

                LOG.debug("Can't access JDK 1.4 encode method ("
                          + e + "). Using deprecated version from now on.");
            }
            catch (InvocationTargetException e)
            {
                LOG.debug("Error using JDK 1.4 encode method ("
                          + e + "). Using deprecated version.");
            }
        }
        return URLEncoder.encode(url);
    }



    // --------------------------------------------- Internal Class -----------

    /**
     * Internal util class to handle representation and
     * encoding of key/value pairs in the query string
     */
    protected final class QueryPair
    {

        private final String key;
        private final Object value;


        /**
         * Construct a new query pair.
         *
         * @param key query pair
         * @param value query value
         */
        public QueryPair(String key, Object value)
        {
            this.key = key;
            this.value = value;
        }

        /**
         * Return the URL-encoded query string.
         */
        public String toString()
        {
            StringBuffer out = new StringBuffer();
            if (value == null)
            {
                out.append(encodeURL(key));
                out.append('=');
                /* Interpret null as "no value" */
            }
            else if (value instanceof List)
            {
                appendAsArray(out, key, ((List)value).toArray());
            }
            else if (value instanceof Object[])
            {
                appendAsArray(out, key, (Object[])value);
            }
            else
            {
                out.append(encodeURL(key));
                out.append('=');
                out.append(encodeURL(String.valueOf(value)));
            }
            return out.toString();
        }

        /* Utility method to avoid logic duplication in toString() */
        private void appendAsArray(StringBuffer out, String key, Object[] arr)
        {
            String encKey = encodeURL(key);
            for (int i=0; i < arr.length; i++)
            {
                out.append(encKey);
                out.append('=');
                if (arr[i] != null)
                {
                    out.append(encodeURL(String.valueOf(arr[i])));
                }
                if (i+1 < arr.length)
                {
                    out.append(queryDataDelim);
                }
            }
        }

    }


}