1/*
2 * Copyright (C) 2010 Google Inc.
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17package org.clearsilver;
18
19import java.io.Closeable;
20import java.io.IOException;
21import java.util.Date;
22import java.util.TimeZone;
23
24/**
25 * This interface establishes the API for an HDF data structure used by
26 * Clearsilver templates when rendering content.
27 */
28public interface HDF extends Closeable {
29
30  /**
31   * Clean up CS object state.
32   */
33  void close();
34
35  /**
36   * Loads the contents of the specified HDF file from disk into the current
37   * HDF object.  The loaded contents are merged with the existing contents.
38   */
39  boolean readFile(String filename) throws IOException;
40
41  /**
42   * Get the file loader in use, if any.
43   * @return the file loader in use.
44   */
45  CSFileLoader getFileLoader();
46
47  /**
48   * Set the CS file loader to use
49   * @param fileLoader the file loader that should be used.
50   */
51  void setFileLoader(CSFileLoader fileLoader);
52
53  /**
54   * Serializes HDF contents to a file (readable by readFile)
55   */
56  boolean writeFile(String filename) throws IOException;
57
58  /**
59   * Parses/loads the contents of the given string as HDF into the current
60   * HDF object.  The loaded contents are merged with the existing contents.
61   */
62  boolean readString(String data);
63
64  /**
65   * Serializes HDF contents to a string (readable by readString)
66   */
67  String writeString();
68
69  /**
70   * Retrieves the integer value at the specified path in this HDF node's
71   * subtree.  If the value does not exist, or cannot be converted to an
72   * integer, default_value will be returned.
73   */
74  int getIntValue(String hdfName, int defaultValue);
75
76  /**
77   * Retrieves the value at the specified path in this HDF node's subtree.
78   */
79  String getValue(String hdfName, String defaultValue);
80
81  /**
82   * Sets the value at the specified path in this HDF node's subtree.
83   */
84  void setValue(String hdfName, String value);
85
86  /**
87   * Remove the specified subtree.
88   */
89  void removeTree(String hdfName);
90
91  /**
92   * Links the src hdf name to the dest.
93   */
94  void setSymLink(String hdfNameSrc, String hdfNameDest);
95
96  /**
97   * Export a date to a clearsilver tree using a specified timezone
98   */
99  void exportDate(String hdfName, TimeZone timeZone, Date date);
100
101  /**
102   * Export a date to a clearsilver tree using a specified timezone
103   */
104  void exportDate(String hdfName, String tz, int tt);
105
106  /**
107   * Retrieves the HDF object that is the root of the subtree at hdfpath, or
108   * null if no object exists at that path.
109   */
110  HDF getObj(String hdfpath);
111
112  /**
113   * Retrieves the HDF for the first child of the root of the subtree
114   * at hdfpath, or null if no child exists of that path or if the
115   * path doesn't exist.
116   */
117  HDF getChild(String hdfpath);
118
119  /**
120   * Return the root of the tree where the current node lies.  If the
121   * current node is the root, return this. Implementations may not
122   * necessarily return the same instance of {@code HDF} every time.
123   * Use {@link #belongsToSameRoot(HDF)} to check if two {@code HDF}s
124   * belong to the same root.
125   */
126  HDF getRootObj();
127
128  /**
129   * Checks if the given hdf object belongs to the same root HDF object
130   * as this one.
131   *
132   * @param hdf The hdf object to compare to.
133   * @throws IllegalArgumentException If the supplied hdf object is from
134   *         a different implementation (e.g. mixing JNI and jsilver).
135   */
136  boolean belongsToSameRoot(HDF hdf);
137
138  /**
139   * Retrieves the HDF object that is the root of the subtree at
140   * hdfpath, create the subtree if it doesn't exist
141   */
142  HDF getOrCreateObj(String hdfpath);
143
144  /**
145   * Returns the name of this HDF node.   The root node has no name, so
146   * calling this on the root node will return null.
147   */
148  String objName();
149
150  /**
151   * Returns the value of this HDF node, or null if this node has no value.
152   * Every node in the tree can have a value, a child, and a next peer.
153   */
154  String objValue();
155
156  /**
157   * Returns the child of this HDF node, or null if there is no child.
158   * Use this in conjunction with objNext to walk the HDF tree.  Every node
159   * in the tree can have a value, a child, and a next peer.
160   */
161  HDF objChild();
162
163  /**
164   * Returns the child of this HDF node, or null if there is no child.
165   * Use this in conjunction with objNext to walk the HDF tree.  Every node
166   * in the tree can have a value, a child, and a next peer.
167   */
168  HDF objNext();
169
170  /**
171   * Deep copy of the contents of the source HDF structure to this HDF
172   * starting at the specified HDF path node.
173   * <p>
174   * This method copies over the attributes and value of the node and recurses
175   * through all the children of the source node.  Any symlink in the source
176   * node becomes a symlink in the copy.
177   * <p>
178   * @param hdfpath the node within this HDF where the source structure should
179   * be copied to.
180   * @param src the source HDF to copy over.
181   */
182  void copy(String hdfpath, HDF src);
183
184  /**
185   * Generates a string representing the content of the HDF tree rooted at
186   * this node.
187   */
188  String dump();
189}
190
191