1 /*****************************************************************************/ 2 /* Software Testing Automation Framework (STAF) */ 3 /* (C) Copyright IBM Corp. 2001 */ 4 /* */ 5 /* This software is licensed under the Eclipse Public License (EPL) V1.0. */ 6 /*****************************************************************************/ 7 8 package com.ibm.staf; 9 10 /** 11 * This class is the primary class used to communicate with STAF. 12 * It is used to register with STAF, submit service requests to STAF, and 13 * unregister with STAF. 14 * <p> 15 * Each Java application using STAF should generally create one and only one 16 * <code>STAFHandle</code> object. The act of creating this object registers 17 * the Java application with STAF. 18 * <p> 19 * There are two constuctors for the <code>STAFHandle</code> class: 20 * <ul compact> 21 * <li>The first (and standard) constructor allows you to specify a string 22 * containing the name by which your handle should be known. 23 * <li>The second constructor allows you to specify an integer which is the 24 * number of an existing STAF static handle. It returns an instance of a 25 * <code>STAFHandle</code> object referencing this existing static handle. 26 * </ul> 27 * <p> 28 * Once you have a valid <code>STAFHandle</code> instance object, you can 29 * begin submitting requests to STAF services by one of two methods: 30 * <ul compact> 31 * <li>The <code>submit</code> method works in the traditional Java fashion 32 * in that it throws an exception, a <code>STAFException</code> in particular, 33 * if it encounters an error and it returns a result string on success. 34 * <li>The <code>submit2</code> method returns a <code>STAFResult</code> 35 * object in all cases. This object contains the real STAF return code as 36 * well as the result string. In addition, if auto-unmarshalling is enabled 37 * for the handle that called the <code>submit2</code> method, the 38 * <code>STAFResult</code> object also contains the marshalling context for 39 * the result (the unmarshalled result) in the <code>resultContext</code> field 40 * and the result object (the root object of the marshalling context) in the 41 * <code>resultObj</code> field. Otherwise, if auto-unmarshalling is disabled, 42 * the <code>resultContext</code> and <code>resultObj</code> fields in the 43 * <code>STAFResult</code> object will be set to <code>null</code>. 44 * </ul> 45 * <p> 46 * Note that a <code>STAFHandle</code> instance object has an auto-unmarshall 47 * result member variable that defaults to true when a <code>STAFHandle</code> 48 * instance object is created, but can be set to false via its 49 * <code>setDoUnmarshallResult</code> method. When set to true, this causes 50 * the STAF result to be automatically unmarshalled when using the 51 * <code>submit2</code> method. 52 * <p> 53 * Before the Java application exits, it should unregister with STAF by calling 54 * the <code>unRegister</code> method. 55 * <p> 56 * This class is fully re-entrant. In general, only one <code>STAFHandle</code> 57 * object should be created for use by the entire Java application. 58 */ 59 public class STAFHandle 60 { 61 /** 62 * This indicates the request should be submitted synchronously so that 63 * the request will not return until the request has completed.. 64 * This is equivalent to calling the <code>submit</code> method. 65 */ 66 public static final int ReqSync = 0; 67 68 /** 69 * This indicates the request should be submitted asynchronously with 70 * no means to determine if the request was successful or not. 71 * The request number will be passed back in the result buffer. 72 * The request's results will not be sent to the submitter's queue nor 73 * will they be retained by the Service service. 74 */ 75 public static final int ReqFireAndForget = 1; 76 77 /** 78 * This indicates the request should be submitted asynchronously with 79 * the request number passed back in the result buffer and when the 80 * request completes, the results will be placed on the submitter's 81 * queue. 82 */ 83 public static final int ReqQueue = 2; 84 85 /** 86 * This indicates the request should be submitted asynchronously with 87 * the request number passed back in the result buffer and when the 88 * request completes, the submitter can determine the results of the 89 * request by using the FREE command of the Service service. 90 * 91 * @see <a href="http://staf.sourceforge.net/current/STAFUG.htm#HDRSRVREQF"> 92 * Section "8.16.6 FREE" in the STAF User's Guide</a> 93 */ 94 public static final int ReqRetain = 3; 95 96 /** 97 * This indicates the request should be submitted asynchronously with 98 * the request number passed back in the result buffer and when the 99 * request completes, the results will be placed on the submitter's queue 100 * The submitter should also free the results of the request by using the 101 * FREE command of the Service service. 102 * 103 * @see <a href="http://staf.sourceforge.net/current/STAFUG.htm#HDRSRVREQF"> 104 * Section "8.16.6 FREE" in the STAF User's Guide</a> 105 */ 106 public static final int ReqQueueRetain = 4; 107 108 // Constructors 109 /** 110 * This is the standard constructor used to create a STAF handle. 111 * It allows you to assign a name by which this handle should be known. 112 * 113 * @param handleName the name by which this handle should should be 114 * known 115 * @throws STAFException thrown if an error occurs creating a STAF handle 116 */ STAFHandle(String handleName)117 public STAFHandle(String handleName) throws STAFException 118 { 119 STAFRegister(handleName); 120 } 121 122 /** 123 * This constructs a STAF handle that references an existing static handle. 124 * 125 * @param staticHandleNumber the number of the existing STAF static handle 126 * that you want to reference 127 */ STAFHandle(int staticHandleNumber)128 public STAFHandle(int staticHandleNumber) 129 { 130 handle = staticHandleNumber; 131 } 132 133 /** 134 * Submits a request to a STAF service on a specified system and waits for 135 * it to complete. It throws an <code>STAFException</code> if it 136 * encounters an error and it returns a result string on success. 137 * 138 * @param where the system to submit the STAF service request to 139 * @param service the name of the STAF service to submit the 140 * request to 141 * @param request the request to submit to the STAF service 142 * @return a string containing the result from the STAF 143 * service request if successful 144 * @throws STAFException if the STAF service request does not complete 145 * successfully (that is, with a non-zero return 146 * code) 147 */ submit(String where, String service, String request)148 public String submit(String where, String service, String request) 149 throws STAFException 150 { 151 return STAFSubmit(ReqSync, where, service, request); 152 } 153 154 /** 155 * Submits a request to a STAF service on a specified system in either a 156 * synchronous or non-synchronous manner based on the specified 157 * <code>syncOption</code> argument. When and what it returns in the 158 * result string depends on the <code>syncOption</code> argument. 159 * It throws an <code>STAFException</code> if it encounters an error and 160 * it returns a result string on success. 161 * 162 * @param syncOption specifies whether to submit the STAF service 163 * request synchronously or in an asyncronous 164 * manner. Specify one of the following: 165 * {@link #ReqSync ReqSync}, 166 * {@link #ReqFireAndForget ReqFireAndForget}, 167 * {@link #ReqQueue ReqQueue}, 168 * {@link #ReqRetain ReqRetain}, 169 * {@link #ReqQueueRetain ReqQueueRetain} 170 * @param where the system to submit the STAF service request to 171 * @param service the name of the STAF service to submit the 172 * request to 173 * @param request the request to submit to the STAF service 174 * @return a string containing the result from the STAF 175 * service request if successful 176 * @throws STAFException if the STAF service request does not complete 177 * successfully (that is, with a non-zero return 178 * code) 179 */ submit(int syncOption, String where, String service, String request)180 public String submit(int syncOption, String where, 181 String service, String request) 182 throws STAFException 183 { 184 return STAFSubmit(syncOption, where, service, request); 185 } 186 187 /** 188 * Submits a request to a STAF service on a specified system and waits 189 * for the request to complete and returns a <code>STAFResult</code> 190 * object containing its return code and result string. 191 * 192 * @param where the system to submit the STAF service request to 193 * @param service the name of the STAF service to submit the 194 * request to 195 * @param request the request to submit to the STAF service 196 * @return a STAFResult object containing the return code 197 * and result string from the STAF service request 198 * @see com.ibm.staf.STAFResult 199 */ submit2(String where, String service, String request)200 public STAFResult submit2(String where, String service, String request) 201 { 202 STAFResult result = STAFSubmit2(ReqSync, where, service, request); 203 204 return new STAFResult(result.rc, result.result, doUnmarshallResult); 205 } 206 207 /** 208 * Submits a request to a STAF service on a specified system in either a 209 * synchronous or non-synchronous manner based on the specified 210 * <code>syncOption</code> argument. When it returns and what it returns 211 * in the <code>STAFResult</code> object depends on the 212 * <code>syncOption</code> argument. 213 * 214 * @param syncOption specifies whether to submit the STAF service 215 * request synchronously or in an asyncronous 216 * manner. Specify one of the following: 217 * {@link #ReqSync ReqSync}, 218 * {@link #ReqFireAndForget ReqFireAndForget}, 219 * {@link #ReqQueue ReqQueue}, 220 * {@link #ReqRetain ReqRetain}, 221 * {@link #ReqQueueRetain ReqQueueRetain} 222 * @param where the system to submit the STAF service request to 223 * @param service the name of the STAF service to submit the 224 * request to 225 * @param request the request to submit to the STAF service 226 * @return a STAFResult object containing the return code 227 * and result string from the STAF service request 228 * @see com.ibm.staf.STAFResult 229 */ submit2(int syncOption, String where, String service, String request)230 public STAFResult submit2(int syncOption, String where, 231 String service, String request) 232 { 233 STAFResult result = STAFSubmit2(syncOption, where, service, request); 234 235 return new STAFResult(result.rc, result.result, doUnmarshallResult); 236 } 237 238 /** 239 * Unregisters this handle with STAF. 240 * 241 * @throws STAFException if the handle is not unregistered successfully 242 */ unRegister()243 public void unRegister() throws STAFException 244 { 245 STAFUnRegister(); 246 } 247 248 /** 249 * Sets a flag to indicates whether the result should be auto-unmarshalled. 250 * 251 * @param flag <code>true</code> if the result should be auto-unmarshalled 252 * or <code>false</code> if the result should not be 253 * auto-unmarshalled 254 */ setDoUnmarshallResult(boolean flag)255 public void setDoUnmarshallResult(boolean flag) 256 { 257 doUnmarshallResult = flag; 258 } 259 260 /** 261 * Retrieves the auto-unmarshall result flag. 262 * 263 * @return the auto-unmarshall result flag 264 */ getDoUnmarshallResult()265 public boolean getDoUnmarshallResult() 266 { 267 return doUnmarshallResult; 268 } 269 270 /** 271 * Retrieves the internal STAF handle number. 272 * 273 * @return the internal STAF handle number 274 */ getHandle()275 public int getHandle() { return handle; } 276 277 // Instance variable to keep the STAF Handle for this class 278 private int handle; 279 280 // Flag to indicate whether the result should be auto-unmarshalled 281 boolean doUnmarshallResult = true; 282 283 /************************/ 284 /* All the native stuff */ 285 /************************/ 286 initialize()287 private static native void initialize(); STAFRegister(String handleName)288 private native void STAFRegister(String handleName); STAFUnRegister()289 private native void STAFUnRegister(); STAFSubmit(int syncOption, String where, String service, String request)290 private native String STAFSubmit(int syncOption, String where, 291 String service, String request); STAFSubmit2(int syncOption, String where, String service, String request)292 private native STAFResult STAFSubmit2(int syncOption, String where, 293 String service, String request); 294 295 // Static initializer - called first time class is loaded. 296 static 297 { 298 if ((System.getProperty("os.name").toLowerCase().indexOf("aix") == 0) || 299 (System.getProperty("os.name").toLowerCase().indexOf("linux") == 0) || 300 ((System.getProperty("os.name").toLowerCase().indexOf("sunos") == 0) 301 && (System.getProperty("os.arch").equals("sparc")))) 302 { 303 System.loadLibrary("STAF"); 304 } 305 306 System.loadLibrary("JSTAF"); initialize()307 initialize(); 308 } 309 } 310