13063267543

Committed 30 Jan 2025 11:34PM UTC coverage: 68.379% (-0.2%) from 68.557%

Build # 13063267543

Build Type

push

github

Committed by

web-flow

Commit Message

#954: improve repository support (#990)

Co-authored-by: jan-vcapgemini <59438728+jan-vcapgemini@users.noreply.github.com>
Co-authored-by: jan-vcapgemini <jan-vincent.hoelzle@capgemini.com>

Run Details

2857 of 4597 branches covered (62.15%)

Branch coverage included in aggregate %.

7391 of 10390 relevant lines covered (71.14%)

3.1 hits per line

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

55.0

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.
   */
  @Override
  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}.
   * @return {@code true} on success, {@code false} on error.
   */
  default boolean run(Runnable stepCode) {

    return run(stepCode, false);
  }

  /**
   * @param stepCode the {@link Runnable} to {@link Runnable#run() execute} for this {@link Step}.
   * @param rethrow - {@code true} to rethrow a potential {@link Throwable error}.
   * @return {@code true} on success, {@code false} on error (if {@code rethrow} is {@code false}).
   */
  default boolean run(Runnable stepCode, boolean rethrow) {

    try {
      stepCode.run();
      if (getSuccess() == null) {
        success();
      }
      return true;
    } catch (RuntimeException | Error e) {
      error(e);
      if (rethrow) {
        throw e;
      }
      return false;
    } 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());	5✔
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	@Override
109	void close();
110
111	/**
112	* Should be called to end this {@link Step} as {@link #isFailure() failure} with an explicit error message. May be called only once.
113	*
114	* @param message the explicit message to log as error.
115	*/
116	default void error(String message) {
117
118	error(null, message);	4✔
119	}	1✔
120
121	/**
122	* 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
123	* only once.
124	*
125	* @param message the explicit message to log as error.
126	* @param args the optional arguments to fill as placeholder into the {@code message}.
127	*/
128	default void error(String message, Object... args) {
129
130	error(null, message, args);	×
131	}	×
132
133	/**
134	* 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
135	* only once.
136	*
137	* @param error the catched {@link Throwable}.
138	*/
139	default void error(Throwable error) {
140
141	error(error, false);	4✔
142	}	1✔
143
144	/**
145	* 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
146	* only once.
147	*
148	* @param error the catched {@link Throwable}.
149	* @param suppress to suppress the error logging (if error will be rethrown and duplicated error messages shall be avoided).
150	*/
151	default void error(Throwable error, boolean suppress) {
152
153	assert (error != null);	4!
154	error(error, suppress, null, (Object[]) null);	7✔
155	}	1✔
156
157	/**
158	* 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
159	* only once.
160	*
161	* @param error the catched {@link Throwable}. May be {@code null} if only a {@code message} is provided.
162	* @param message the explicit message to log as error.
163	*/
164	default void error(Throwable error, String message) {
165
166	error(error, message, (Object[]) null);	6✔
167	}	1✔
168
169	/**
170	* 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
171	* only once.
172	*
173	* @param error the catched {@link Throwable}. May be {@code null} if only a {@code message} is provided.
174	* @param message the explicit message to log as error.
175	* @param args the optional arguments to fill as placeholder into the {@code message}.
176	*/
177	default void error(Throwable error, String message, Object... args) {
178
179	error(error, false, message, args);	6✔
180	}	1✔
181
182	/**
183	* 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
184	* only once.
185	*
186	* @param error the catched {@link Throwable}. May be {@code null} if only a {@code message} is provided.
187	* @param suppress to suppress the error logging (if error will be rethrown and duplicated error messages shall be avoided).
188	* @param message the explicit message to log as error.
189	* @param args the optional arguments to fill as placeholder into the {@code message}.
190	*/
191	void error(Throwable error, boolean suppress, String message, Object... args);
192
193	/**
194	* @return the parent {@link Step} or {@code null} if there is no parent.
195	*/
196	Step getParent();
197
198	/**
199	* @param i the index of the requested parameter. Should be in the range from {@code 0} to
200	* <code>{@link #getParameterCount()}-1</code>.
201	* @return the parameter at the given index {@code i} or {@code null} if no such parameter exists.
202	*/
203	Object getParameter(int i);
204
205	/**
206	* @return the number of {@link #getParameter(int) parameters}.
207	*/
208	int getParameterCount();
209
210	/**
211	* @param stepCode the {@link Runnable} to {@link Runnable#run() execute} for this {@link Step}.
212	* @return {@code true} on success, {@code false} on error.
213	*/
214	default boolean run(Runnable stepCode) {
215
216	return run(stepCode, false);	5✔
217	}
218
219	/**
220	* @param stepCode the {@link Runnable} to {@link Runnable#run() execute} for this {@link Step}.
221	* @param rethrow - {@code true} to rethrow a potential {@link Throwable error}.
222	* @return {@code true} on success, {@code false} on error (if {@code rethrow} is {@code false}).
223	*/
224	default boolean run(Runnable stepCode, boolean rethrow) {
225
226	try {
227	stepCode.run();	2✔
228	if (getSuccess() == null) {	3!
229	success();	2✔
230	}
231	return true;	4✔
232	} catch (RuntimeException \| Error e) {	1✔
233	error(e);	3✔
234	if (rethrow) {	2!
235	throw e;	×
236	}
237	return false;	4✔
238	} finally {
239	close();	2✔
240	}
241	}
242
243	/**
244	* @param stepCode the {@link Callable} to {@link Callable#call() execute} for this {@link Step}.
245	* @param <R> type of the return value.
246	* @return the value returned from {@link Callable#call()}.
247	*/
248	default <R> R call(Callable<R> stepCode) {
249
250	try {
251	R result = stepCode.call();	×
252	if (getSuccess() == null) {	×
253	success();	×
254	}
255	return result;	×
256	} catch (Throwable e) {	×
257	error(e);	×
258	if (e instanceof RuntimeException re) {	×
259	throw re;	×
260	} else if (e instanceof Error error) {	×
261	throw error;	×
262	} else {
263	throw new IllegalStateException(e);	×
264	}
265	} finally {
266	close();	×
267	}
268	}
269	}

devonfw / IDEasy / 13063267543

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