<?xml version="1.0" encoding="UTF-8"?>
<!--
  Licensed to the Apache Software Foundation (ASF) under one or more
  contributor license agreements.  See the NOTICE file distributed with
  this work for additional information regarding copyright ownership.
  The ASF licenses this file to You under the Apache License, Version 2.0
  (the "License"); you may not use this file except in compliance with
  the License.  You may obtain a copy of the License at

      http://www.apache.org/licenses/LICENSE-2.0

  Unless required by applicable law or agreed to in writing, software
  distributed under the License is distributed on an "AS IS" BASIS,
  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  See the License for the specific language governing permissions and
  limitations under the License.
-->
<!DOCTYPE document [
  <!ENTITY project SYSTEM "project.xml">
]>
<document url="service.html">

  &project;

  <properties>
    <author email="craigmcc@apache.org">Craig R. McClanahan</author>
    <title>The Service Component</title>
  </properties>

<body>

<section name="Table of Contents">
<toc/>
</section>

<section name="Introduction">

  <p>A <strong>Service</strong> element represents the combination of one or
  more <strong>Connector</strong> components that share a single
  <a href="engine.html">Engine</a> component for processing incoming
  requests.  One or more <strong>Service</strong> elements may be nested
  inside a <a href="server.html">Server</a> element.</p>

</section>


<section name="Attributes">

  <subsection name="Common Attributes">

  <p>All implementations of <strong>Service</strong>
  support the following attributes:</p>

  <attributes>

    <attribute name="className" required="false">
      <p>Java class name of the implementation to use.  This class must
      implement the <code>org.apache.catalina.Service</code> interface.
      If no class name is specified, the standard implementation will
      be used.</p>
    </attribute>

    <attribute name="name" required="true">
      <p>The display name of this <strong>Service</strong>, which will
      be included in log messages if you utilize standard Catalina
      components.  The name of each <strong>Service</strong> that is
      associated with a particular <a href="server.html">Server</a>
      must be unique.</p>
    </attribute>

  </attributes>

  </subsection>

  <subsection name="Standard Implementation">

  <p>The standard implementation of <strong>Service</strong> is
  <strong>org.apache.catalina.core.StandardService</strong>.
  It supports the following additional attributes (in addition to the
  common attributes listed above):</p>

  <attributes>

    <attribute name="gracefulStopAwaitMillis" required="false">
      <p>The time to wait, in milliseconds, when stopping the Service for the
      client connections to finish processing and close before the Service's
      container hierarchy is stopped. The wait only applies to Connectors
      configured with a <code>bindOnInit</code> value of <code>false</code>.
      Any value of zero or less means there will be no wait. If not specified,
      the default value of zero will be used.</p>
    </attribute>

  </attributes>

  </subsection>

</section>


<section name="Nested Components">

  <p>The only components that may be nested inside a <strong>Service</strong>
  element are one or more <strong>Connector</strong> elements,
  followed by exactly one <a href="engine.html">Engine</a> element.</p>

</section>


<section name="Special Features">

  <p>There are no special features associated with a <strong>Service</strong>.
  </p>

</section>


</body>

</document>
