View Javadoc

1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one
3    * or more contributor license agreements.  See the NOTICE file
4    * distributed with this work for additional information
5    * regarding copyright ownership.  The ASF licenses this file
6    * to you under the Apache License, Version 2.0 (the
7    * "License"); you may not use this file except in compliance
8    * with the License.  You may obtain a copy of the License at
9    *
10   *   http://www.apache.org/licenses/LICENSE-2.0
11   *
12   * Unless required by applicable law or agreed to in writing,
13   * software distributed under the License is distributed on an
14   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
15   * KIND, either express or implied.  See the License for the
16   * specific language governing permissions and limitations
17   * under the License.
18   */
19  package org.apache.myfaces.trinidad.render;
20  
21  import java.io.Serializable;
22  
23  import javax.faces.component.UIComponent;
24  import javax.faces.context.FacesContext;
25  
26  /**
27   * This class manages server-side
28   * rowkey Objects with client-side string keys.
29   * This class must be Serializable as it is state-saved along with the
30   * UIComponent state.
31   */
32  public abstract class ClientRowKeyManager implements Serializable
33  {
34    /**
35     * Gets a string version of a key that identifies the row with the given rowkey. 
36     * This string key can be used on the client-side to identify the row.
37     * If a string key for the given rowkey does not exist, then a new one is
38     * created. The lifespan of this string rowkey is entirely upto each
39     * implementation. Implementors must ensure that if a particular row is still
40     * present on the client-side, then its string key must also continue to be valid.
41     * @param rowKey the rowkey to convert into a client key. Note that
42     * null is special and is not allowed.
43     */
44    public abstract String getClientRowKey(FacesContext context, UIComponent component, Object rowKey);
45  
46    /**
47     * Gets the corresponding server-side rowkey object from the given client-side string
48     * key. If the string key has expired, implementors should return null. However,
49     * if any part of a row is still present on the client-side, its corresponding
50     * string-key may not expire.
51     * @param clientRowKey the string key
52     * @return null, if the string key has expired, or never existed.
53     */
54    public abstract Object getRowKey(FacesContext context, UIComponent component, String clientRowKey);
55    
56    
57    /**
58     * Replaces an old row key with a new key if the old row key exists.  If the old row key is successfully replaced,
59     * the new row key will be mapped to the existing client row key.
60     * @param context
61     * @param component
62     * @param oldRowKey row key to replace (may not exist)
63     * @param newRowKey new row key
64     * @return <code>true</code> if old row key existed and was replaced, <code>false</code> otherwise
65     */
66    public boolean replaceRowKey(FacesContext context, UIComponent component, Object oldRowKey, Object newRowKey)
67    {
68      // default implementation to maintain backwards compatibility
69      return false;
70    }
71    
72    private static final long serialVersionUID = 1L;
73  }