blob: a685e8afa74dd70967a06b80135e6f39eb4998cd [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>Apache TomEE</title>
<meta name="description"
content="Apache TomEE is a lightweight, yet powerful, JavaEE Application server with feature rich tooling." />
<meta name="keywords" content="tomee,asf,apache,javaee,jee,shade,embedded,test,junit,applicationcomposer,maven,arquillian" />
<meta name="author" content="Luka Cvetinovic for Codrops" />
<link rel="icon" href="../../favicon.ico">
<link rel="icon" type="image/png" href="../../favicon.png">
<meta name="msapplication-TileColor" content="#80287a">
<meta name="theme-color" content="#80287a">
<link rel="stylesheet" type="text/css" href="../../css/normalize.css">
<link rel="stylesheet" type="text/css" href="../../css/bootstrap.css">
<link rel="stylesheet" type="text/css" href="../../css/owl.css">
<link rel="stylesheet" type="text/css" href="../../css/animate.css">
<link rel="stylesheet" type="text/css" href="../../fonts/font-awesome-4.1.0/css/font-awesome.min.css">
<link rel="stylesheet" type="text/css" href="../../fonts/eleganticons/et-icons.css">
<link rel="stylesheet" type="text/css" href="../../css/jqtree.css">
<link rel="stylesheet" type="text/css" href="../../css/idea.css">
<link rel="stylesheet" type="text/css" href="../../css/cardio.css">
<script type="text/javascript">
var _gaq = _gaq || [];
_gaq.push(['_setAccount', 'UA-2717626-1']);
_gaq.push(['_setDomainName', 'apache.org']);
_gaq.push(['_trackPageview']);
(function() {
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
})();
</script>
</head>
<body>
<div class="preloader">
<img src="../../img/loader.gif" alt="Preloader image">
</div>
<nav class="navbar">
<div class="container">
<div class="row"> <div class="col-md-12">
<!-- Brand and toggle get grouped for better mobile display -->
<div class="navbar-header">
<button type="button" class="navbar-toggle collapsed" data-toggle="collapse" data-target="#bs-example-navbar-collapse-1">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="/">
<span>
<img src="../../img/logo-active.png">
</span>
Apache TomEE
</a>
</div>
<!-- Collect the nav links, forms, and other content for toggling -->
<div class="collapse navbar-collapse" id="bs-example-navbar-collapse-1">
<ul class="nav navbar-nav navbar-right main-nav">
<li><a href="../../docs.html">Documentation</a></li>
<li><a href="../../community/index.html">Community</a></li>
<li><a href="../../security/security.html">Security</a></li>
<li><a href="../../download-ng.html">Downloads</a></li>
</ul>
</div>
<!-- /.navbar-collapse -->
</div></div>
</div>
<!-- /.container-fluid -->
</nav>
<div id="main-block" class="container main-block">
<div class="row title">
<div class="col-md-12">
<div class='page-header'>
<h1>MicroProfile Custom Health Check</h1>
</div>
</div>
</div>
<div class="row">
<div class="col-md-12">
<div class="paragraph">
<p>This is an example of how to use MicroProfile Custom Health Check in TomEE.</p>
</div>
<h4 id="_health_feature" class="discrete">Health Feature</h4>
<div class="paragraph">
<p>Health checks are used to probe the state of services and resources that an application might depend on or even to expose its
state, e.g. in a cluster environment, where an unhealthy node needs to be discarded (terminated, shutdown) and eventually
replaced by another healthy instance.</p>
</div>
<div class="paragraph">
<p>By default, <a href="https://github.com/eclipse/microprofile-health">microprofile-health-api</a> provides a basic output of a node by
simply hitting the endpoint <a href="http://host:port/health" class="bare">http://host:port/health</a>.</p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-json" data-lang="json">{"checks":[],"outcome":"UP","status":"UP"}</code></pre>
</div>
</div>
<div class="paragraph">
<p>To provide a customized output, Let&#8217;s say we have an application that uses a Weather API, and if the service becomes
unavailable, we should report the service as DOWN.</p>
</div>
<div class="paragraph">
<p>To begin with a customized output, is needed to implement the interface <a href="https://github.com/eclipse/microprofile-health/blob/master/api/src/main/java/org/eclipse/microprofile/health/HealthCheck.java">HealthCheck</a>,
make the class a managed bean by annotating it with <code>@ApplicationScoped</code> plus with <code>@Health</code> annotation to active the custom check.
See more here <a href="https://github.com/apache/geronimo-health/blob/master/geronimo-health/src/main/java/org/apache/geronimo/microprofile/impl/health/cdi/GeronimoHealthExtension.java">GeronimoHealthExtension.java</a></p>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-java" data-lang="java">@Health
@ApplicationScoped
public class WeatherServiceHealthCheck implements HealthCheck {
@Inject WeatherGateway weatherGateway;
@Override
public HealthCheckResponse call() {
HealthCheckResponseBuilder responseBuilder = HealthCheckResponse.named("OpenWeatherMap");
try {
WeatherApiStatus status = weatherGateway.getApiStatus();
return responseBuilder.withData("weatherServiceApiUrl", status.getUrl())
.withData("weatherServiceApiVersion", status.getVersion())
.withData("weatherServiceMessage", status.getMessage())
.up().build();
} catch (WeatherException e) {
return responseBuilder.withData("weatherServiceErrorMessage", e.getMessage()).down().build();
}
}
}</code></pre>
</div>
</div>
<div class="paragraph">
<p>In the example above, the health probe name is <a href="https://openweathermap.org/appid">OpenWeatherMap</a> (<em>illustrative only</em>) which provides a
subscription plan to access its services and if the limit of calls is exceeded the API becomes unavailable until it&#8217;s renewed.</p>
</div>
<h3 id="_examples" class="discrete">Examples</h3>
<div class="listingblock">
<div class="title">Running the application</div>
<div class="content">
<pre> mvn clean install tomee:run</pre>
</div>
</div>
<h4 id="_example_1" class="discrete">Example 1</h4>
<div class="paragraph">
<p>When hitting /health endpoint, OpenWeatherMap tell us that our remaining calls are running out and we should take
an action before it gets unavailable.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>curl http://localhost:8080/mp-custom-healthcheck/health</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-json" data-lang="json">{
"checks":[
{
"data":{
"weatherServiceApiVersion":"2.5",
"weatherServiceMessage":"Your account will become unavailable soon due to limitation of your
subscription type. Remaining API calls are 1",
"weatherServiceApiUrl":"http://api.openweathermap.org/data/2.5/"
},
"name":"OpenWeatherMap",
"state":"UP"
}
],
"outcome":"UP",
"status":"UP"
}</code></pre>
</div>
</div>
<h4 id="_example_2" class="discrete">Example 2</h4>
<div class="paragraph">
<p>Weather API still working fine.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>curl http://localhost:8080/mp-custom-healthcheck/weather/day/status</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-text" data-lang="text">Hi, today is a sunny day!</code></pre>
</div>
</div>
<h4 id="_example_3" class="discrete">Example 3</h4>
<div class="paragraph">
<p>When hitting one more time /health endpoint, OpenWeatherMap tell us that our account is temporary blocked and this
service is being reported as DOWN.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>curl http://localhost:8080/mp-custom-healthcheck/health</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-json" data-lang="json">{
"checks":[
{
"data":{
"weatherServiceErrorMessage":"Your account is temporary blocked due to exceeding of
requests limitation of your subscription type. Please choose the proper subscription
http://openweathermap.org/price"
},
"name":"weatherservice",
"state":"DOWN"
}
],
"outcome":"DOWN",
"status":"DOWN"
}</code></pre>
</div>
</div>
<h4 id="_example_4" class="discrete">Example 4</h4>
<div class="paragraph">
<p>Weather API has stopped.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>curl http://localhost:8080/mp-custom-healthcheck/weather/day/status</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre class="highlight"><code class="language-text" data-lang="text">Weather Service is unavailable at moment, retry later.</code></pre>
</div>
</div>
<h5 id="_running_the_tests" class="discrete">Running the tests</h5>
<div class="paragraph">
<p>You can also try it out using the <a href="src/test/java/org/superbiz/rest/WeatherServiceTest.java">WeatherServiceTest.java</a> available in the project.</p>
</div>
<div class="listingblock">
<div class="content">
<pre>mvn clean test</pre>
</div>
</div>
<div class="listingblock">
<div class="content">
<pre>[INFO] Results:
[INFO]
[INFO] Tests run: 4, Failures: 0, Errors: 0, Skipped:</pre>
</div>
</div>
</div>
</div>
</div>
<footer>
<div class="container">
<div class="row">
<div class="col-sm-6 text-center-mobile">
<h3 class="white">Be simple. Be certified. Be Tomcat.</h3>
<h5 class="light regular light-white">"A good application in a good server"</h5>
<ul class="social-footer">
<li><a href="https://www.facebook.com/ApacheTomEE/"><i class="fa fa-facebook"></i></a></li>
<li><a href="https://twitter.com/apachetomee"><i class="fa fa-twitter"></i></a></li>
<li><a href="https://plus.google.com/communities/105208241852045684449"><i class="fa fa-google-plus"></i></a></li>
</ul>
</div>
<div class="col-sm-6 text-center-mobile">
<div class="row opening-hours">
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../latest/docs/" class="white">Documentation</a></h5>
<ul class="list-unstyled">
<li><a href="../../latest/docs/admin/configuration/index.html" class="regular light-white">How to configure</a></li>
<li><a href="../../latest/docs/admin/file-layout.html" class="regular light-white">Dir. Structure</a></li>
<li><a href="../../latest/docs/developer/testing/index.html" class="regular light-white">Testing</a></li>
<li><a href="../../latest/docs/admin/cluster/index.html" class="regular light-white">Clustering</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../latest/examples/" class="white">Examples</a></h5>
<ul class="list-unstyled">
<li><a href="../../latest/examples/simple-cdi-interceptor.html" class="regular light-white">CDI Interceptor</a></li>
<li><a href="../../latest/examples/rest-cdi.html" class="regular light-white">REST with CDI</a></li>
<li><a href="../../latest/examples/ejb-examples.html" class="regular light-white">EJB</a></li>
<li><a href="../../latest/examples/jsf-managedBean-and-ejb.html" class="regular light-white">JSF</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../community/index.html" class="white">Community</a></h5>
<ul class="list-unstyled">
<li><a href="../../community/contributors.html" class="regular light-white">Contributors</a></li>
<li><a href="../../community/social.html" class="regular light-white">Social</a></li>
<li><a href="../../community/sources.html" class="regular light-white">Sources</a></li>
</ul>
</div>
<div class="col-sm-3 text-center-mobile">
<h5><a href="../../security/index.html" class="white">Security</a></h5>
<ul class="list-unstyled">
<li><a href="http://apache.org/security" target="_blank" class="regular light-white">Apache Security</a></li>
<li><a href="http://apache.org/security/projects.html" target="_blank" class="regular light-white">Security Projects</a></li>
<li><a href="http://cve.mitre.org" target="_blank" class="regular light-white">CVE</a></li>
</ul>
</div>
</div>
</div>
</div>
<div class="row bottom-footer text-center-mobile">
<div class="col-sm-12 light-white">
<p>Copyright &copy; 1999-2016 The Apache Software Foundation, Licensed under the Apache License, Version 2.0. Apache TomEE, TomEE, Apache, the Apache feather logo, and the Apache TomEE project logo are trademarks of The Apache Software Foundation. All other marks mentioned may be trademarks or registered trademarks of their respective owners.</p>
</div>
</div>
</div>
</footer>
<!-- Holder for mobile navigation -->
<div class="mobile-nav">
<ul>
<li><a hef="../../latest/docs/admin/index.html">Administrators</a>
<li><a hef="../../latest/docs/developer/index.html">Developers</a>
<li><a hef="../../latest/docs/advanced/index.html">Advanced</a>
<li><a hef="../../community/index.html">Community</a>
</ul>
<a href="#" class="close-link"><i class="arrow_up"></i></a>
</div>
<!-- Scripts -->
<script src="../../js/jquery-1.11.1.min.js"></script>
<script src="../../js/owl.carousel.min.js"></script>
<script src="../../js/bootstrap.min.js"></script>
<script src="../../js/wow.min.js"></script>
<script src="../../js/typewriter.js"></script>
<script src="../../js/jquery.onepagenav.js"></script>
<script src="../../js/tree.jquery.js"></script>
<script src="../../js/highlight.pack.js"></script>
<script src="../../js/main.js"></script>
</body>
</html>