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 17 package org.clearsilver; 18 19 import java.io.Closeable; 20 import java.io.IOException; 21 import java.util.Date; 22 import 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 */ 28 public interface HDF extends Closeable { 29 30 /** 31 * Clean up CS object state. 32 */ close()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 */ readFile(String filename)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 */ getFileLoader()45 CSFileLoader getFileLoader(); 46 47 /** 48 * Set the CS file loader to use 49 * @param fileLoader the file loader that should be used. 50 */ setFileLoader(CSFileLoader fileLoader)51 void setFileLoader(CSFileLoader fileLoader); 52 53 /** 54 * Serializes HDF contents to a file (readable by readFile) 55 */ writeFile(String filename)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 */ readString(String data)62 boolean readString(String data); 63 64 /** 65 * Serializes HDF contents to a string (readable by readString) 66 */ writeString()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 */ getIntValue(String hdfName, int defaultValue)74 int getIntValue(String hdfName, int defaultValue); 75 76 /** 77 * Retrieves the value at the specified path in this HDF node's subtree. 78 */ getValue(String hdfName, String defaultValue)79 String getValue(String hdfName, String defaultValue); 80 81 /** 82 * Sets the value at the specified path in this HDF node's subtree. 83 */ setValue(String hdfName, String value)84 void setValue(String hdfName, String value); 85 86 /** 87 * Remove the specified subtree. 88 */ removeTree(String hdfName)89 void removeTree(String hdfName); 90 91 /** 92 * Links the src hdf name to the dest. 93 */ setSymLink(String hdfNameSrc, String hdfNameDest)94 void setSymLink(String hdfNameSrc, String hdfNameDest); 95 96 /** 97 * Export a date to a clearsilver tree using a specified timezone 98 */ exportDate(String hdfName, TimeZone timeZone, Date date)99 void exportDate(String hdfName, TimeZone timeZone, Date date); 100 101 /** 102 * Export a date to a clearsilver tree using a specified timezone 103 */ exportDate(String hdfName, String tz, int tt)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 */ getObj(String hdfpath)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 */ getChild(String hdfpath)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 */ getRootObj()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 */ belongsToSameRoot(HDF hdf)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 */ getOrCreateObj(String hdfpath)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 */ objName()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 */ objValue()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 */ objChild()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 */ objNext()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 */ copy(String hdfpath, HDF src)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 */ dump()188 String dump(); 189 } 190 191