On Apr 20, 2015, at 7:33 PM, Roger Riggs <roger.ri...@oracle.com> wrote:
> Hi Paul,
>
> There are statements in Process about the specified behavior of Processes
> created by ProcessBuilder. That's why I included them in the @implSpec
> clause.
> If @implSpec is only for the specifics of the method itself then where
> should the behavior of ProcessBuilder created instances be specified?
>
I think the @implNote you have on Process.onExit about Processes from
ProcessBuilder being more efficient is fine, but that @implNote also appears to
mix stuff that is @implSpec for the method itself.
For Process.supportsNormalTermination i would presume the @implSpec should be
similar to that of toHandle. I don't think there needs to be anything said
about Process from ProcessBuilder on this method this as it should "naturally"
conform to what is stated.
Perhaps you can state something in the class doc of Process and or
ProcessBuilder about the behaviour of such Process instances? It would seem to
flow from the general statement you added to Process about overriding.
Paul.
> Thanks, Roger
>
>
>
> On 4/20/2015 12:33 PM, Paul Sandoz wrote:
>> 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/
>
