// 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:hgw@onetsoft.com">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();
}