link.java

欢迎使用 FastJsp 开发框架! 编译说明： * 若要生成Api Javadoc文档

// Copyright 2005-2007 onetsoft.com
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package com.onetsoft.fastjsp;

import java.util.Map;

/**
 * 页面链接
 * 构造页面链接应调用{@link Component#getLink(String)}
 * 注：添加参数时，须注意：
 * 1.系统自动对第一个 append() 调用尝试静态url参数构造。因此，应该有意识的对第一个append()调用设置有意义的页面参数，如：userID
 * 2.所有 {@link #appendAction(String)} 和 {@link #append(java.util.Map)} 均构造为动态查询参数
 * 3.参数名称应该满足{@link Character#isLetterOrDigit(char)}条件，系统也不再作此检测。
 * 4.关于 staticParamPerfered 静态优先：false时，按上述规则1尝试构造静态参数，但有个限制：最多不超过1个name-vlaue参数对，若此为true，无此限制
 * (只要参数字符满足规则3)。
 * 一般调用顺序：
 * ............append(NORMAL页面定位参数) > append(STATIC) -> append(其他)
 *
 * @author <a href="mailto:[e-mail]">hgw</a>
 */
public interface Link extends Cloneable {

    /*"静态name-vlaue参数对"优先，数量不受限制*/
    public final static int STATIC = 0;

    /*"强制查询参数对"，强制为查询参数构造*/
    public final static int QUERY = 1;

    /*"常规构造方式(缺省)"，对第一个append(name,value)尝试按STATIC构造，其余调用按QUERY构造。append(map),appendAction(name)总按QUERY构造。*/
    public final static int NORMAL = 2;

    /**
     * 添加 url action
     *
     * @param action
     * @return
     */
    Link appendAction(String action);

    /**
     * 取得 URL
     *
     * @return
     */
    String getURL();

    /**
     * 添加参数
     * 注：空值参数将忽略
     *
     * @param param
     * @param value
     * @return
     */
    Link append(String param, String value);

    /**
     * 添加参数
     *
     * @param param
     * @param value
     * @param paramPerfered 参数构造方式
     * @return
     */
    Link append(String param, String value, int paramPerfered);

    Link append(String param, long value);

    Link append(String param, long value, int paramPerfered);

    Link append(String param, int value);

    Link append(String param, int value, int paramPerfered);

    Link append(String param, double value);

    Link append(String param, double value, int paramPerfered);

    Link append(String param, boolean value);

    Link append(String param, boolean value,int paramPerfered);


    /**
     * 以 map 形式添加参数
     * 相对于其它<tt>append</tt>添加的参数，此参数集在链接最后生成时才添加
     * 注：1.若URL参数已经添加，则 map 中的不再重复添加 2.空值或null参数将添加为查询参数
     *
     * @param params
     * @return
     * @since 3.0
     */
    Link append(Map params);

    /**
     * 增加锚点
     *
     * @param anchorName
     * @return
     */
    Link appendAnchor(String anchorName);

    /**
     * 克隆此链接对象
     * 注：此方法
     *
     * @return
     */
    public Object clone();
}