9660998058

Committed 25 Jun 2024 10:43AM UTC coverage: 60.42% (-0.06%) from 60.475%

Build # 9660998058

Build Type

push

github

Committed by

web-flow

Commit Message

#171: support for multiple VariableSyntax styles (#407)

Run Details

1898 of 3450 branches covered (55.01%)

Branch coverage included in aggregate %.

4985 of 7942 relevant lines covered (62.77%)

2.74 hits per line

Source File
Press 'n' to go to next uncovered line, 'b' for previous

36.36

cli/src/main/java/com/devonfw/tools/ide/step/Step.java

package com.devonfw.tools.ide.step;

import java.util.concurrent.Callable;

/**
 * Interface for a {@link Step} of the process. Allows to split larger processes into smaller steps that are traced and measured. At the end you can get a
 * report with the hierarchy of all steps and their success/failure status, duration in absolute and relative numbers to gain transparency.<br> The typical use
 * should follow this pattern:
 *
 * <pre>
 * Step step = context.{@link com.devonfw.tools.ide.context.IdeContext#newStep(String) newStep}("My step description");
 * try {
 *   // ... do something ...
 *   step.{@link #success(String) success}("Did something successfully.");
 * } catch (Exception e) {
 *   step.{@link #error(Throwable, String) error}(e, "Failed to do something.");
 * } finally {
 *   step.{@link #close()};
 * }
 * </pre>
 * {@link Step} also extends {@link AutoCloseable} so you can also use try-with-resource syntax:
 * <pre>
 * try (Step step = context.{@link com.devonfw.tools.ide.context.IdeContext#newStep(String) newStep}("My step description")) {
 *   // ... do something ...
 *   try {
 *     // ... stuff that may cause an exception ...
 *     step.{@link #success()};
 *   } catch (Exception e) {
 *     step.{@link #error(Throwable, String) error}(e, "Failed to do something.");
 *   }
 * }
 * </pre>
 */
public interface Step extends AutoCloseable {

  /**
   * Empty object array for no parameters.
   */
  Object[] NO_PARAMS = new Object[0];

  /**
   * @return the name of this {@link Step} as given to constructor.
   */
  String getName();

  /**
   * @return the duration of this {@link Step} from construction to {@link #success()} or {@link #close()}. Will be {@code 0} if not {@link #close() ended}.
   */
  long getDuration();

  /**
   * @return {@code Boolean#TRUE} if this {@link Step} has {@link #success() succeeded}, {@code Boolean#FALSE} if the {@link Step} has {@link #close() ended}
   * without {@link #success() success} and {@code null} if the {@link Step} is still running.
   */
  Boolean getSuccess();

  /**
   * @return {@code true} if this step completed {@link #success() successfully}, {@code false} otherwise.
   */
  default boolean isSuccess() {

    return Boolean.TRUE.equals(getSuccess());
  }

  /**
   * @return {@code true} if this step {@link #close() ended} without {@link #success() success} e.g. with an {@link #error(String) error}, {@code false}
   * otherwise.
   */
  default boolean isFailure() {

    return Boolean.FALSE.equals(getSuccess());
  }

  /**
   * @return {@code true} if this step is silent and not logged by default, {@code false} otherwise (default).
   */
  boolean isSilent();

  /**
   * Should be called to end this {@link Step} {@link #getSuccess() successfully}. May be called only once.
   */
  default void success() {

    success(null);
  }

  /**
   * Should be called to end this {@link Step} {@link #getSuccess() successfully}. May be called only once.
   *
   * @param message the explicit message to log as success.
   */
  default void success(String message) {

    success(message, (Object[]) null);
  }

  /**
   * Should be called to end this {@link Step} {@link #getSuccess() successfully}. May be called only once.
   *
   * @param message the explicit message to log as success.
   * @param args    the optional arguments to fill as placeholder into the {@code message}.
   */
  void success(String message, Object... args);

  /**
   * Ensures this {@link Step} is properly ended. Has to be called from a finally block.
   */
  void close();

  /**
   * Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message. May be called only once.
   *
   * @param message the explicit message to log as error.
   */
  default void error(String message) {

    error(null, message);
  }

  /**
   * Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
   * only once.
   *
   * @param message the explicit message to log as error.
   * @param args    the optional arguments to fill as placeholder into the {@code message}.
   */
  default void error(String message, Object... args) {

    error(null, message, args);
  }

  /**
   * Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
   * only once.
   *
   * @param error the catched {@link Throwable}.
   */
  default void error(Throwable error) {

    error(error, false);
  }

  /**
   * Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
   * only once.
   *
   * @param error    the catched {@link Throwable}.
   * @param suppress to suppress the error logging (if error will be rethrown and duplicated error messages shall be avoided).
   */
  default void error(Throwable error, boolean suppress) {

    assert (error != null);
    error(error, suppress, null, (Object[]) null);
  }

  /**
   * Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
   * only once.
   *
   * @param error   the catched {@link Throwable}. May be {@code null} if only a {@code message} is provided.
   * @param message the explicit message to log as error.
   */
  default void error(Throwable error, String message) {

    error(error, message, (Object[]) null);
  }

  /**
   * Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
   * only once.
   *
   * @param error   the catched {@link Throwable}. May be {@code null} if only a {@code message} is provided.
   * @param message the explicit message to log as error.
   * @param args    the optional arguments to fill as placeholder into the {@code message}.
   */
  default void error(Throwable error, String message, Object... args) {

    error(error, false, message, args);
  }

  /**
   * Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
   * only once.
   *
   * @param error    the catched {@link Throwable}. May be {@code null} if only a {@code message} is provided.
   * @param suppress to suppress the error logging (if error will be rethrown and duplicated error messages shall be avoided).
   * @param message  the explicit message to log as error.
   * @param args     the optional arguments to fill as placeholder into the {@code message}.
   */
  void error(Throwable error, boolean suppress, String message, Object... args);

  /**
   * @return the parent {@link Step} or {@code null} if there is no parent.
   */
  Step getParent();

  /**
   * @param i the index of the requested parameter. Should be in the range from {@code 0} to
   *          <code>{@link #getParameterCount()}-1</code>.
   * @return the parameter at the given index {@code i} or {@code null} if no such parameter exists.
   */
  Object getParameter(int i);

  /**
   * @return the number of {@link #getParameter(int) parameters}.
   */
  int getParameterCount();

  /**
   * @param stepCode the {@link Runnable} to {@link Runnable#run() execute} for this {@link Step}.
   */
  default void run(Runnable stepCode) {

    try {
      stepCode.run();
      if (getSuccess() == null) {
        success();
      }
    } catch (RuntimeException | Error e) {
      error(e);
      throw e;
    } finally {
      close();
    }
  }

  /**
   * @param stepCode the {@link Callable} to {@link Callable#call() execute} for this {@link Step}.
   * @param <R>      type of the return value.
   * @return the value returned from {@link Callable#call()}.
   */
  default <R> R call(Callable<R> stepCode) {

    try {
      R result = stepCode.call();
      if (getSuccess() == null) {
        success();
      }
      return result;
    } catch (Throwable e) {
      error(e);
      if (e instanceof RuntimeException re) {
        throw re;
      } else if (e instanceof Error error) {
        throw error;
      } else {
        throw new IllegalStateException(e);
      }
    } finally {
      close();
    }
  }
}

1	package com.devonfw.tools.ide.step;
2
3	import java.util.concurrent.Callable;
4
5	/**
6	* Interface for a {@link Step} of the process. Allows to split larger processes into smaller steps that are traced and measured. At the end you can get a
7	* report with the hierarchy of all steps and their success/failure status, duration in absolute and relative numbers to gain transparency.<br> The typical use
8	* should follow this pattern:
9	*
10	* <pre>
11	* Step step = context.{@link com.devonfw.tools.ide.context.IdeContext#newStep(String) newStep}("My step description");
12	* try {
13	* // ... do something ...
14	* step.{@link #success(String) success}("Did something successfully.");
15	* } catch (Exception e) {
16	* step.{@link #error(Throwable, String) error}(e, "Failed to do something.");
17	* } finally {
18	* step.{@link #close()};
19	* }
20	* </pre>
21	* {@link Step} also extends {@link AutoCloseable} so you can also use try-with-resource syntax:
22	* <pre>
23	* try (Step step = context.{@link com.devonfw.tools.ide.context.IdeContext#newStep(String) newStep}("My step description")) {
24	* // ... do something ...
25	* try {
26	* // ... stuff that may cause an exception ...
27	* step.{@link #success()};
28	* } catch (Exception e) {
29	* step.{@link #error(Throwable, String) error}(e, "Failed to do something.");
30	* }
31	* }
32	* </pre>
33	*/
34	public interface Step extends AutoCloseable {	2!
35
36	/**
37	* Empty object array for no parameters.
38	*/
39	Object[] NO_PARAMS = new Object[0];	4✔
40
41	/**
42	* @return the name of this {@link Step} as given to constructor.
43	*/
44	String getName();
45
46	/**
47	* @return the duration of this {@link Step} from construction to {@link #success()} or {@link #close()}. Will be {@code 0} if not {@link #close() ended}.
48	*/
49	long getDuration();
50
51	/**
52	* @return {@code Boolean#TRUE} if this {@link Step} has {@link #success() succeeded}, {@code Boolean#FALSE} if the {@link Step} has {@link #close() ended}
53	* without {@link #success() success} and {@code null} if the {@link Step} is still running.
54	*/
55	Boolean getSuccess();
56
57	/**
58	* @return {@code true} if this step completed {@link #success() successfully}, {@code false} otherwise.
59	*/
60	default boolean isSuccess() {
61
62	return Boolean.TRUE.equals(getSuccess());	×
63	}
64
65	/**
66	* @return {@code true} if this step {@link #close() ended} without {@link #success() success} e.g. with an {@link #error(String) error}, {@code false}
67	* otherwise.
68	*/
69	default boolean isFailure() {
70
71	return Boolean.FALSE.equals(getSuccess());	×
72	}
73
74	/**
75	* @return {@code true} if this step is silent and not logged by default, {@code false} otherwise (default).
76	*/
77	boolean isSilent();
78
79	/**
80	* Should be called to end this {@link Step} {@link #getSuccess() successfully}. May be called only once.
81	*/
82	default void success() {
83
84	success(null);	3✔
85	}	1✔
86
87	/**
88	* Should be called to end this {@link Step} {@link #getSuccess() successfully}. May be called only once.
89	*
90	* @param message the explicit message to log as success.
91	*/
92	default void success(String message) {
93
94	success(message, (Object[]) null);	5✔
95	}	1✔
96
97	/**
98	* Should be called to end this {@link Step} {@link #getSuccess() successfully}. May be called only once.
99	*
100	* @param message the explicit message to log as success.
101	* @param args the optional arguments to fill as placeholder into the {@code message}.
102	*/
103	void success(String message, Object... args);
104
105	/**
106	* Ensures this {@link Step} is properly ended. Has to be called from a finally block.
107	*/
108	void close();
109
110	/**
111	* Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message. May be called only once.
112	*
113	* @param message the explicit message to log as error.
114	*/
115	default void error(String message) {
116
117	error(null, message);	4✔
118	}	1✔
119
120	/**
121	* Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
122	* only once.
123	*
124	* @param message the explicit message to log as error.
125	* @param args the optional arguments to fill as placeholder into the {@code message}.
126	*/
127	default void error(String message, Object... args) {
128
129	error(null, message, args);	×
130	}	×
131
132	/**
133	* Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
134	* only once.
135	*
136	* @param error the catched {@link Throwable}.
137	*/
138	default void error(Throwable error) {
139
140	error(error, false);	4✔
141	}	1✔
142
143	/**
144	* Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
145	* only once.
146	*
147	* @param error the catched {@link Throwable}.
148	* @param suppress to suppress the error logging (if error will be rethrown and duplicated error messages shall be avoided).
149	*/
150	default void error(Throwable error, boolean suppress) {
151
152	assert (error != null);	4!
153	error(error, suppress, null, (Object[]) null);	7✔
154	}	1✔
155
156	/**
157	* Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
158	* only once.
159	*
160	* @param error the catched {@link Throwable}. May be {@code null} if only a {@code message} is provided.
161	* @param message the explicit message to log as error.
162	*/
163	default void error(Throwable error, String message) {
164
165	error(error, message, (Object[]) null);	6✔
166	}	1✔
167
168	/**
169	* Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
170	* only once.
171	*
172	* @param error the catched {@link Throwable}. May be {@code null} if only a {@code message} is provided.
173	* @param message the explicit message to log as error.
174	* @param args the optional arguments to fill as placeholder into the {@code message}.
175	*/
176	default void error(Throwable error, String message, Object... args) {
177
178	error(error, false, message, args);	6✔
179	}	1✔
180
181	/**
182	* Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message and/or {@link Throwable exception}. May be called
183	* only once.
184	*
185	* @param error the catched {@link Throwable}. May be {@code null} if only a {@code message} is provided.
186	* @param suppress to suppress the error logging (if error will be rethrown and duplicated error messages shall be avoided).
187	* @param message the explicit message to log as error.
188	* @param args the optional arguments to fill as placeholder into the {@code message}.
189	*/
190	void error(Throwable error, boolean suppress, String message, Object... args);
191
192	/**
193	* @return the parent {@link Step} or {@code null} if there is no parent.
194	*/
195	Step getParent();
196
197	/**
198	* @param i the index of the requested parameter. Should be in the range from {@code 0} to
199	* <code>{@link #getParameterCount()}-1</code>.
200	* @return the parameter at the given index {@code i} or {@code null} if no such parameter exists.
201	*/
202	Object getParameter(int i);
203
204	/**
205	* @return the number of {@link #getParameter(int) parameters}.
206	*/
207	int getParameterCount();
208
209	/**
210	* @param stepCode the {@link Runnable} to {@link Runnable#run() execute} for this {@link Step}.
211	*/
212	default void run(Runnable stepCode) {
213
214	try {
215	stepCode.run();	×
216	if (getSuccess() == null) {	×
217	success();	×
218	}
219	} catch (RuntimeException \| Error e) {	×
220	error(e);	×
221	throw e;	×
222	} finally {
223	close();	×
224	}
225	}	×
226
227	/**
228	* @param stepCode the {@link Callable} to {@link Callable#call() execute} for this {@link Step}.
229	* @param <R> type of the return value.
230	* @return the value returned from {@link Callable#call()}.
231	*/
232	default <R> R call(Callable<R> stepCode) {
233
234	try {
235	R result = stepCode.call();	×
236	if (getSuccess() == null) {	×
237	success();	×
238	}
239	return result;	×
240	} catch (Throwable e) {	×
241	error(e);	×
242	if (e instanceof RuntimeException re) {	×
243	throw re;	×
244	} else if (e instanceof Error error) {	×
245	throw error;	×
246	} else {
247	throw new IllegalStateException(e);	×
248	}
249	} finally {
250	close();	×
251	}
252	}
253	}

devonfw / IDEasy / 9660998058

Source File Press 'n' to go to next uncovered line, 'b' for previous

Source File
Press 'n' to go to next uncovered line, 'b' for previous