Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.apache.tapestry5
Interface Link

All Known Implementing Classes:
  LinkImpl

    public interface Link

A link is the Tapestry representation of a URL or URI that triggers dynamic behavior. This link is in three parts: a path portion, an optional anchor, and a set of query parameters. A request for a link will ultimately be recognized by a `Dispatcher`.

Query parameter values are kept separate from the path portion to support encoding those values into hidden form fields (where appropriate).

Method Summary
`void` | `addParameter(java.lang.String parameterName, java.lang.String value)` Adds a parameter value.
`Link` | `addParameterValue(java.lang.String parameterName, java.lang.Object value)` Adds a parameter value as a value object; the value object is converted to a string via `ContextPathEncoder.encodeValue(Object)` and the result is added via `addParameter(String, String)`.
`Link` | `copyWithBasePath(java.lang.String basePath)` Creates a copy of this link that has the same parameters, anchor, and other attributes, but a different base path.
`java.lang.String` | `getAnchor()` Returns the link anchor.
`java.lang.String` | `getBasePath()` Returns the completely unadorned base path.
`java.util.List<java.lang.String>` | `getParameterNames()` Returns the names of any additional query parameters for the URI.
`java.lang.String` | `getParameterValue(java.lang.String name)` Returns the value of a specifically named query parameter, or `null` if no such query parameter is stored in the link.
`java.lang.String[]` | `getParameterValues(java.lang.String parameterName)` Returns the parameter values for the given name.
`LinkSecurity` | `getSecurity()` Returns the current security for this link, which reflects whether the targetted page is itself secure or insecure.
`void` | `removeParameter(java.lang.String parameterName)` Removes a parameter value, which is occasionally useful when transforming a parameter into a portion of the path.
`void` | `setAnchor(java.lang.String anchor)` Sets the link anchor.
`void` | `setSecurity(LinkSecurity newSecurity)` Changes the link's security, which can be useful to force a link to be either secure or insecure when normally it might not be.
`java.lang.String` | `toAbsoluteURI()` Returns the absolute URL, which includes the scheme, hostname and possibly port (as per `BaseURLSource.getBaseURL(boolean)`).
`java.lang.String` | `toAbsoluteURI(boolean secure)` Returns either the secure or insecure URL, with complete scheme, hostname and possibly port (as per `BaseURLSource.getBaseURL(boolean)`).
`java.lang.String` | `toRedirectURI()` Returns the link as a redirect URI.
`java.lang.String` | `toURI()` Returns the URI portion of the link.

Method Detail

### getParameterNames

    java.util.List<java.lang.String> getParameterNames()

  Returns the names of any additional query parameters for the URI. Query parameters store less regular or less often used values that can not be expressed in the path. They also are used to store, or link to, persistent state.

  Returns:
    list of query parameter names, is alphabetical order

### getParameterValue

    java.lang.String getParameterValue(java.lang.String name)

  Returns the value of a specifically named query parameter, or `null` if no such query parameter is stored in the link.

  Use this method only when you are sure the parameter has only one value. If the parameter might have more than one value, use `getParameterValues(java.lang.String)`.

  If you use this method with a multivalued parameter, the value returned is equal to the first value in the array returned by `getParameterValues`.

  Returns:
    a string representing the single value of the named parameter

### addParameter

    void addParameter(java.lang.String parameterName,
                      java.lang.String value)

  Adds a parameter value. The value will be added, as is, to the URL. In many cases, the value should be URL encoded via `URLCodec`.

  Parameters:
    `parameterName` - the name of the parameter to store
    `value` - the value to store, a null or blank value is allowed (as of Tapestry 5.3)

### addParameterValue

    Link addParameterValue(java.lang.String parameterName,
                           java.lang.Object value)

  Adds a parameter value as a value object; the value object is converted to a string via `ContextPathEncoder.encodeValue(Object)` and the result is added via `addParameter(String, String)`. The Link object is returned for further configuration.

  Since:
    5.2.2

### removeParameter

    void removeParameter(java.lang.String parameterName)

  Removes a parameter value, which is occasionally useful when transforming a parameter into a portion of the path.

  Since:
    5.2.0

### getBasePath

    java.lang.String getBasePath()

  Returns the completely unadorned base path. Other methods (such as `toURI()`), may append an anchor or query parameters.

  Since:
    5.2.0

### copyWithBasePath

    Link copyWithBasePath(java.lang.String basePath)

  Creates a copy of this link that has the same parameters, anchor, and other attributes, but a different base path.

  Since:
    5.2.0

### toURI

    java.lang.String toURI()

  Returns the URI portion of the link. When the link is created for a form, this will not include query parameters. This is the same value returned from toString().

  Returns:
    the URI, ready to be added as an element attribute

### toRedirectURI

    java.lang.String toRedirectURI()

  Returns the link as a redirect URI. The URI includes any query parameters.

### getAnchor

    java.lang.String getAnchor()

  Returns the link anchor. If this link does not have an anchor, this method returns `null`.

  Returns:
    the link anchor

### setAnchor

    void setAnchor(java.lang.String anchor)

  Sets the link anchor. Null and empty anchors will be ignored when building the link URI.

  Parameters:
    `anchor` - the link anchor

### toAbsoluteURI

    java.lang.String toAbsoluteURI()

  Returns the absolute URL, which includes the scheme, hostname and possibly port (as per `BaseURLSource.getBaseURL(boolean)`). By default, the scheme is chosen to match the current requests security.

  Note: the semantics of this method changed between Tapestry 5.1 and 5.2. Most code should use toString() or `toURI()` (which are equivalent) instead.

  Returns:
    the complete, qualified URL, including query parameters.

### toAbsoluteURI

    java.lang.String toAbsoluteURI(boolean secure)

  Returns either the secure or insecure URL, with complete scheme, hostname and possibly port (as per `BaseURLSource.getBaseURL(boolean)`).

  Returns:
    the complete, qualified URL, including query parameters.
  Since:
    5.2.2

### setSecurity

    void setSecurity(LinkSecurity newSecurity)

  Changes the link's security, which can be useful to force a link to be either secure or insecure when normally it might not be.

  Parameters:
    `newSecurity` - new security value, not null, typically `LinkSecurity.FORCE_SECURE` or `LinkSecurity.FORCE_INSECURE`
  Since:
    5.3

### getSecurity

    LinkSecurity getSecurity()

  Returns the current security for this link, which reflects whether the targetted page is itself secure or insecure.

  Since:
    5.3

### getParameterValues

    java.lang.String[] getParameterValues(java.lang.String parameterName)

  Returns the parameter values for the given name. Returns null if no such parameter is stored in the link.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2003-2012 The Apache Software Foundation.