View Javadoc

1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  package org.apache.http.impl.client.cache.memcached;
28  
29  import org.apache.http.client.cache.HttpCacheEntry;
30  
31  /**
32   * Provides for serialization and deserialization of higher-level
33   * {@link HttpCacheEntry} objects into byte arrays suitable for
34   * storage in memcached. Clients wishing to change the serialization
35   * mechanism from the provided defaults should implement this
36   * interface as well as {@link MemcachedCacheEntryFactory}.
37   */
38  public interface MemcachedCacheEntry {
39  
40      /**
41       * Returns a serialized representation of the current cache entry.
42       */
43      byte[] toByteArray();
44  
45      /**
46       * Returns the storage key associated with this entry. May return
47       * {@code null} if this is an "unset" instance waiting to be
48       * {@link #set(byte[])} with a serialized representation.
49       */
50      String getStorageKey();
51  
52      /**
53       * Returns the {@link HttpCacheEntry} associated with this entry.
54       * May return {@code null} if this is an "unset" instance
55       * waiting to be {@link #set(byte[])} with a serialized
56       * representation.
57       */
58      HttpCacheEntry getHttpCacheEntry();
59  
60      /**
61       * Given a serialized representation of a {@link MemcachedCacheEntry},
62       * attempt to reconstitute the storage key and {@link HttpCacheEntry}
63       * represented therein. After a successful call to this method, this
64       * object should return updated (as appropriate) values for
65       * {@link #getStorageKey()} and {@link #getHttpCacheEntry()}. This
66       * should be viewed as an atomic operation on the
67       * {@code MemcachedCacheEntry}.
68       *
69       * @param bytes serialized representation
70       * @throws MemcachedSerializationException if deserialization
71       *   fails. In this case, the prior values for {{@link #getStorageKey()}
72       *   and {@link #getHttpCacheEntry()} should remain unchanged.
73       */
74      void set(byte[] bytes);
75  
76  }