/*
- When bailing out mid-cycle to sleep, 
leave state SAMPLING, so that other clients can't disturb

- May need to change initServiceState to behave 

- use new method setEntryPoint(flags) to determine
which steps whould be done on reentry.
- use new method setExitSleep(boolean) to allow
service to exit and sleep after some method
- use existing methods to resync timer to wake
at appropriate time


- may need to change return type of acquire or allow NULL

*/
   public synchronized SensorDataPacket acquire(boolean logSample)
	throws NoDataException {


       // initServiceState does:
       // throws exception if SUSPENDED
       // calls run() if !_running
       // setStatusSampling
       // managePowerWake
	initServiceState();

	String name = new String(getName());

	// prepare device for sampling
	// may not need to do if re-entering
	if(DO_PREPARE)
	try {
	    // may call setEntryPoint(DO_PREPARE|DO_REQUEST|DO_READ|DO_PROCESS...)
	    // may resync service
	    prepareToSample();
	} catch (Exception e) {
	    // reset state here
	    setStatusError();
	    managePowerSleep();
	    annotate("ERR: while preparing to sample".getBytes());
	    throw new NoDataException(e.getMessage());
	}

	// may wish to bail out here to sleep thru
	// long warmup
	if(DO_EXIT_SLEEP){
	    DO_EXIT_SLEEP=FALSE
	    return NULL;
	}

	for (tries ) {

	    try {

		// Send sample request to instrument
		// may call setEntryPoint(DO_PREPARE|DO_REQUEST|DO_READ|DO_PROCESS...)
		// may resync service
		if(DO_REQUEST)
		requestSample();

		// may wish to bail out here to sleep thru
		// long sample cycle
		if(DO_EXIT_SLEEP){
		    DO_EXIT_SLEEP=FALSE
		    return NULL;
		}

		// Read raw sample from instrument
		if(DO_READ)
		if ((nBytes = readSample(_sampleBuf)) <= 0) {
		    _log4j.warn(name + ": readSample() failed");
		    errMsg.append("readSample returned 0 bytes;");
		    incRetryCount();
		    continue;
		}

		if(DO_VALIDATE)
		validateSample(_sampleBuf, nBytes);


		SensorDataPacket dataPacket = processSample(_sampleBuf, nBytes);

		if(DO_POST)
		postSample();

		// turn off power
		managePowerSleep();

		if (logSample) {
		    logPacket(dataPacket);
		}

		setStatusOk();

		printData(dataPacket.dataBuffer());

		return dataPacket;
	    } catch (Exceptions...) {
		// make error message
	    }

	    // other Exceptions fly past into the caller
	    Thread.yield();
	}

	setStatusError();

	postSample();

	managePowerSleep();

	annotate(errMsg.toString().getBytes());

	throw new NoDataException(retryMsg);
    }