timeShift function docs update. #672
Conversation
xdocs/usermanual/functions.xml
Outdated
| See <a href="https://docs.oracle.com/javase/8/docs/api/java/time/format/DateTimeFormatter.html">DateTimeFormatter</a> | ||
| If omitted, the function uses milliseconds since epoch format. | ||
| If omitted, the function returns milliseconds. |
There was a problem hiding this comment.
While it returns milliseconds, those are anchored at start of the unix epoch. Hence I think that detail should not be dropped.
There was a problem hiding this comment.
Yes, You are right. I mean that when format is not given and date to shift is given (and must be Long) the code is reduced to result that don't seem explicitly connect with epoch:
Duration duration = Duration.parse("PT10S");
ZoneId systemDefaultZoneID = ZoneId.systemDefault();
ZonedDateTime zonedDateTimeToShift = ZonedDateTime.ofInstant(Instant.ofEpochMilli(Long.parseLong("10000")), systemDefaultZoneID);
zonedDateTimeToShift = zonedDateTimeToShift.plus(duration);
String result = String.valueOf(zonedDateTimeToShift.toInstant().toEpochMilli());
System.out.println(result); //just 20000ms
But, yes, when date to shift is not given (is default: now) then connection with epoch is seen better:
Duration duration = Duration.parse("PT10S");
ZoneId systemDefaultZoneID = ZoneId.systemDefault();
ZonedDateTime zonedDateTimeToShift = ZonedDateTime.now(systemDefaultZoneID);
zonedDateTimeToShift = zonedDateTimeToShift.plus(duration);
String result = String.valueOf(zonedDateTimeToShift.toInstant().toEpochMilli());
System.out.println(result); //1632157138893ms
xdocs/usermanual/functions.xml
Outdated
| </property> | ||
| <property name="Date to shift" required="No"> | ||
| Indicate the date in the format set by the parameter <code>Format</code> to shift. | ||
| If omitted, the date is set to <em>now</em>. | ||
| If omitted, the date is set to <em>ZonedDateTime.now</em> with system zone <em>ZoneId.systemDefault()</em>. | ||
| If <code>Format</code> parameter is not set then this property (if required) must be set as number of milliseconds eg.: Format="" and "Date to shift"=10000 then if "value to shift"=PT10S then result=20000 (20sec) |
There was a problem hiding this comment.
This last line feels like an example/explaining note to me. Should this be in an extra note paragraph?
At other places in this documentation, we use the code-tag for the name of parameters, when mentioned in the docs, would not this be helpful here, too?
|
Thanks for the PR |
Description
Proposition to add additonal documentation for timeShift function.
Motivation and Context
timeShift is very flexible and has not documented implicite behaviour. This change is loosely connected with https://bz.apache.org/bugzilla/show_bug.cgi?id=65217
How Has This Been Tested?
Change is in functions.xml file so gradle previewSite task was used.
Screenshots (if appropriate):
NA
Types of changes
Only documentation in site, result will be visible on html https://jmeter.apache.org/usermanual/functions.html#__timeShift
Checklist:
NA