001/***************************************************************************** 002 * Copyright by The HDF Group. * 003 * Copyright by the Board of Trustees of the University of Illinois. * 004 * All rights reserved. * 005 * * 006 * This file is part of the HDF Java Products distribution. * 007 * The full copyright notice, including terms governing use, modification, * 008 * and redistribution, is contained in the files COPYING and Copyright.html. * 009 * COPYING can be found at the root of the source code distribution tree. * 010 * Or, see https://support.hdfgroup.org/products/licenses.html * 011 * If you do not have access to either file, you may request a copy from * 012 * help@hdfgroup.org. * 013 ****************************************************************************/ 014 015package hdf.object.h5; 016 017import java.util.List; 018 019import org.slf4j.Logger; 020import org.slf4j.LoggerFactory; 021 022import hdf.hdf5lib.H5; 023import hdf.hdf5lib.HDF5Constants; 024import hdf.hdf5lib.HDFArray; 025import hdf.hdf5lib.HDFNativeData; 026import hdf.hdf5lib.exceptions.HDF5Exception; 027import hdf.hdf5lib.structs.H5O_info_t; 028import hdf.hdf5lib.structs.H5O_token_t; 029 030import hdf.object.Attribute; 031import hdf.object.FileFormat; 032import hdf.object.HObject; 033import hdf.object.MetaDataContainer; 034 035/** 036 * An H5Link object represents an existing HDF5 object in file. 037 * 038 * H5Link object is an HDF5 object that is either a soft or an external link to 039 * an object in a file that does not exist. The type of the object is unknown. 040 * Once the object being linked to is created, and the type is known, then 041 * H5link object will change its type. 042 * 043 * @version 2.7.2 7/6/2010 044 * @author Nidhi Gupta 045 */ 046 047public class H5Link extends HObject implements MetaDataContainer 048{ 049 private static final long serialVersionUID = -8137277460521594367L; 050 051 private static final Logger log = LoggerFactory.getLogger(H5Link.class); 052 053 /** the object properties */ 054 private H5O_info_t objInfo; 055 056 /** 057 * Constructs an HDF5 link with specific name, path, and parent. 058 * 059 * @param theFile 060 * the file which containing the link. 061 * @param theName 062 * the name of this link, e.g. "link1". 063 * @param thePath 064 * the full path of this link, e.g. "/groups/". 065 */ 066 public H5Link(FileFormat theFile, String theName, String thePath) { 067 this(theFile, theName, thePath, null); 068 } 069 070 /** 071 * Constructs an HDF5 link with specific name, path, parent and oid. 072 * 073 * @param theFile 074 * the file which containing the link. 075 * @param theName 076 * the name of this link, e.g. "link1". 077 * @param thePath 078 * the full path of this link, e.g. "/groups/". 079 * @param oid 080 * the oid of this link, e.g. "/groups/". 081 */ 082 @SuppressWarnings("deprecation") 083 public H5Link(FileFormat theFile, String theName, String thePath, long[] oid) { 084 super(theFile, theName, thePath, oid); 085 086 if (theFile != null) { 087 if (oid == null) { 088 // retrieve the object ID 089 byte[] refBuf = null; 090 try { 091 refBuf = H5.H5Rcreate_object(theFile.getFID(), this.getFullName(), HDF5Constants.H5P_DEFAULT); 092 this.oid = HDFNativeData.byteToLong(refBuf); 093 log.trace("constructor REF {} to OID {}", refBuf, this.oid); 094 } 095 catch (Exception ex) { 096 log.debug("constructor ID {} for {} failed H5Rcreate_object", theFile.getFID(), this.getFullName()); 097 } 098 finally { 099 if (refBuf != null) 100 H5.H5Rdestroy(refBuf); 101 } 102 } 103 log.trace("constructor OID {}", this.oid); 104 try { 105 objInfo = H5.H5Oget_info_by_name(theFile.getFID(), this.getFullName(), HDF5Constants.H5O_INFO_BASIC, HDF5Constants.H5P_DEFAULT); 106 } 107 catch (Exception ex) { 108 objInfo = new H5O_info_t(-1L, null, 0, 0, 0L, 0L, 0L, 0L, 0L); 109 } 110 } 111 else { 112 this.oid = null; 113 objInfo = new H5O_info_t(-1L, null, 0, 0, 0L, 0L, 0L, 0L, 0L); 114 } 115 } 116 117 /* 118 * (non-Javadoc) 119 * 120 * @see hdf.object.HObject#open() 121 */ 122 @Override 123 public long open() { 124 return 0; 125 } 126 127 /* 128 * (non-Javadoc) 129 * 130 * @see hdf.object.HObject#close(int) 131 */ 132 @Override 133 public void close(long id) { 134 } 135 136 /** 137 * Get the token for this object. 138 * 139 * @return true if it has any attributes, false otherwise. 140 */ 141 public long[] getToken() { 142 H5O_token_t token = objInfo.token; 143 return HDFNativeData.byteToLong(token.data); 144 } 145 146 /** 147 * Check if the object has any attributes attached. 148 * 149 * @return true if it has any attributes, false otherwise. 150 */ 151 @Override 152 public boolean hasAttribute() { 153 return false; 154 } 155 156 /** 157 * Removes all of the elements from metadata list. 158 * The list should be empty after this call returns. 159 */ 160 @Override 161 public void clear() { 162 } 163 164 /** 165 * Retrieves the object's metadata, such as attributes, from the file. 166 * 167 * Metadata, such as attributes, is stored in a List. 168 * 169 * @return the list of metadata objects. 170 * 171 * @throws HDF5Exception 172 * if the metadata can not be retrieved 173 */ 174 @Override 175 public List<Attribute> getMetadata() throws HDF5Exception { 176 try { 177 this.linkTargetObjName = H5File.getLinkTargetName(this); 178 } 179 catch (Exception ex) { 180 log.debug("getMetadata(): getLinkTargetName failed: ", ex); 181 } 182 183 return null; 184 } 185 186 /** 187 * Retrieves the object's metadata, such as attributes, from the file. 188 * 189 * Metadata, such as attributes, is stored in a List. 190 * 191 * @param attrPropList 192 * the list of properties to get 193 * 194 * @return the list of metadata objects. 195 * 196 * @throws HDF5Exception 197 * if the metadata can not be retrieved 198 */ 199 public List<Attribute> getMetadata(int... attrPropList) throws HDF5Exception { 200 try { 201 this.linkTargetObjName = H5File.getLinkTargetName(this); 202 } 203 catch (Exception ex) { 204 log.debug("getMetadata(): getLinkTargetName failed: ", ex); 205 } 206 207 return null; 208 } 209 210 /** 211 * Writes a specific piece of metadata (such as an attribute) into the file. 212 * 213 * If an HDF(4&5) attribute exists in the file, this method updates its 214 * value. If the attribute does not exist in the file, it creates the 215 * attribute in the file and attaches it to the object. It will fail to 216 * write a new attribute to the object where an attribute with the same name 217 * already exists. To update the value of an existing attribute in the file, 218 * one needs to get the instance of the attribute by getMetadata(), change 219 * its values, then use writeMetadata() to write the value. 220 * 221 * @param info 222 * the metadata to write. 223 * 224 * @throws Exception 225 * if the metadata can not be written 226 */ 227 @Override 228 public void writeMetadata(Object info) throws Exception { 229 } 230 231 /** 232 * Deletes an existing piece of metadata from this object. 233 * 234 * @param info 235 * the metadata to delete. 236 * 237 * @throws HDF5Exception 238 * if the metadata can not be removed 239 */ 240 @Override 241 public void removeMetadata(Object info) throws HDF5Exception { 242 } 243 244 /** 245 * Updates an existing piece of metadata attached to this object. 246 * 247 * @param info 248 * the metadata to update. 249 * 250 * @throws HDF5Exception 251 * if the metadata can not be updated 252 */ 253 @Override 254 public void updateMetadata(Object info) throws HDF5Exception { 255 } 256 257 /* 258 * (non-Javadoc) 259 * 260 * @see hdf.object.HObject#setName(java.lang.String) 261 */ 262 @Override 263 public void setName(String newName) throws Exception { 264 if (newName == null) 265 throw new IllegalArgumentException("The new name is NULL"); 266 267 H5File.renameObject(this, newName); 268 super.setName(newName); 269 } 270}