On Apr 20, 2015, at 5:49 PM, Roger Riggs <roger.ri...@oracle.com> wrote:
> Hi Paul,
>
> On 4/20/2015 9:01 AM, Paul Sandoz wrote:
>> Hi Roger,
>>
>> I am not sure you have the @implSpec/@implNote quite correct on the new
>> methods of Process.
>>
>> For example, for Process.toHandle i would expect something like:
>>
>> ...
>>
>> @implSpec
>> This implementation throws an instance of UnsupportedOperationException and
>> performs no other action. Sub-types should override this method, ensuring
>> that
>> calling methods (getPid etc.) of this class, that are not overridden,
>> operate on the
>> returned ProcessHandle.
>>
>> The @implSpec should refer to the implementation in Process itself, and the
>> @implNote cannot be used for any normative statements.
> Thanks for the reminder and suggested text. I updated the @implSpec clauses.
>
I spotted another one here:
281 /**
282 * Returns {@code true} if the implementation of {@link #destroy} is to
283 * normally terminate the process,
284 * Returns {@code false} if the implementation of {@code destroy}
285 * forcibly and immediately terminates the process.
286 *
287 * @implSpec
288 * Processes returned from ProcessBuilder support this operation to
289 * return true or false depending on the platform implementation.
290 *
291 * @return {@code true} if the implementation of {@link #destroy} is to
292 * normally terminate the process;
293 * otherwise, {@link #destroy} forcibly terminates the process
294 * @throws UnsupportedOperationException if the Process implementation
295 * does not support this operation
296 * @since 1.9
297 */
298 public boolean supportsNormalTermination() {
299 throw new UnsupportedOperationException("supportsNormalTermination
not supported for " + this.getClass().toString());
300 }
The docs of Process.onExit might also require some tweaks. I dunno how much
wiggle room there is with the current implementation, perhaps very little?
415 /**
416 * Returns a ProcessHandle for the Process.
417 *
418 * @implSpec
419 * This implementation throws an instance of
UnsupportedOperationException
420 * and performs no other action.
...
446 * @implSpec
447 * The implementation of this method returns information about the
process as:
448 * {@link #toHandle toHandle().info()}.
Best to be consistent with either "This implementation ..." or "The
implementation of this method ..." rather than a mix. I prefer the former as it
is more concise. Up to you.
> Some @implNotes describe the JDK implementation and some developers will
> rely on the implementation specifics and to some degree define the expected
> behaviors.
One way of thinking about this is that the developers writing the TCK tests
will pay close attention to @implSpec and need not do so for @implNote.
>>
>>
>> The document for Process.getPid (and similarly those methods depending on
>> toHandle) could then be:
>>
>> ...
>> @implSpec
>> This implementation returns a process id as follows:
>>
>> toHandle().getPid();
>>
>>
>> In this respect is there a need to say anything about the behaviour of a
>> Process created by ProcessBuilder?
> The ProcessBuilder produced subclasses of Process implement the spec
> so no additional description is needed.
>>
>> It might be useful to have some general guidance for sub-types on the class
>> doc of Process e.g. saying they only need to override toHandle but may
>> override some or all dependent methods as appropriate.
> It does not add much but I added a paragraph to the Process class javadoc.
> There are not many subclasses of Process outside the JDK.
>
Ok.
Paul.
> The webrev[1] and javadoc[2] have been updated in place.
>
> Thanks, Roger
>
> [1] http://cr.openjdk.java.net/~rriggs/webrev-ph
> [2] http://cr.openjdk.java.net/~rriggs/ph-apidraft/
