    001    package org.apache.turbine.services;
    002
    003
    004    /*
    005     * Licensed to the Apache Software Foundation (ASF) under one
    006     * or more contributor license agreements.  See the NOTICE file
    007     * distributed with this work for additional information
    008     * regarding copyright ownership.  The ASF licenses this file
    009     * to you under the Apache License, Version 2.0 (the
    010     * "License"); you may not use this file except in compliance
    011     * with the License.  You may obtain a copy of the License at
    012     *
    013     *   http://www.apache.org/licenses/LICENSE-2.0
    014     *
    015     * Unless required by applicable law or agreed to in writing,
    016     * software distributed under the License is distributed on an
    017     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
    018     * KIND, either express or implied.  See the License for the
    019     * specific language governing permissions and limitations
    020     * under the License.
    021     */
    022
    023
    024    import org.apache.turbine.pipeline.PipelineData;
    025    import org.apache.turbine.util.RunData;
    026
    027    /**
    028     * <p>This class provides a <code>Service</code> implementation that
    029     * Services used in Turbine are required to extend.  The
    030     * functionality provided in addition to <code>BaseService</code>
    031     * functionality is recognizing objects used in early initialization
    032     * of <code>Services</code> in Turbine, and passing them to
    033     * appropriate convenience methods.  These methods should be overriden
    034     * to provide desired initialization functionality.</p>
    035     *
    036     * <p><strong>Note!</strong><br>Remember to call
    037     * <code>setInit(true)</code> after successful initialization.</p>
    038     *
    039     * <p><strong>Note!</strong><br>If you need to use another
    040     * <code>Service</code> inside your early initialization, remember to
    041     * request initialization of that <code>Service</code> before using
    042     * it:</p>
    043     *
    044     * <pre><code>
    045     * getServiceBroker().initClass("OtherService",data);
    046     * OtherService service =
    047     *         (OtherService)getServiceBroker().getService("OtherService");
    048     * </code></pre>
    049     *
    050     * @author <a href="mailto:greg@shwoop.com">Greg Ritter</a>
    051     * @author <a href="mailto:bmclaugh@algx.net">Brett McLaughlin</a>
    052     * @author <a href="mailto:burton@apache.org">Kevin Burton</a>
    053     * @author <a href="mailto:krzewski@e-point.pl">Rafal Krzewski</a>
    054     * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a>
    055     * @author <a href="mailto:jvanzyl@periapt.com">Jason van Zyl</a>
    056     * @author <a href="mailto:peter@courcoux.biz">Peter Courcoux</a>
    057     * @version $Id: TurbineBaseService.java 1078552 2011-03-06 19:58:46Z tv $
    058     */
    059    public abstract class TurbineBaseService
    060            extends BaseService
    061    {
    062        /**
    063         * Performs early initialization.  Overrides init() method in
    064         * BaseService to detect objects used in Turbine's Service
    065         * initialization and pass them to apropriate init() methods.
    066         *
    067         * @param data An Object to use for initialization activities.
    068         * @exception InitializationException if initialization of this
    069         * class was not successful.
    070         */
    071        @Override
    072        public void init(Object data)
    073                throws InitializationException
    074        {
    075            if (data instanceof RunData)
    076            {
    077                init((RunData) data);
    078            }
    079            else if (data instanceof PipelineData)
    080            {
    081                init((PipelineData) data);
    082            }
    083        }
    084
    085        /**
    086         * Performs early initialization.
    087         *
    088         * @deprecated Use the PipelineData version instead.
    089         * @param data An RunData to use for initialization activities.
    090         * @exception InitializationException if initialization of this
    091         * class was not successful.
    092         */
    093        @Deprecated
    094        public void init(RunData data) throws InitializationException
    095        {
    096            // empty
    097        }
    098
    099        /**
    100         * Performs early initialization.
    101         *
    102         * @param data A PipelineData to use for initialization activities.
    103         * @exception InitializationException if initialization of this
    104         * class was not successful.
    105         */
    106        public void init(PipelineData data) throws InitializationException
    107        {
    108            // empty
    109        }
    110
    111
    112        /**
    113         * Performs late initialization.
    114         *
    115         * If your class relies on early initialization, and the object it
    116         * expects was not received, you can use late initialization to
    117         * throw an exception and complain.
    118         *
    119         * @exception InitializationException, if initialization of this
    120         * class was not successful.
    121         */
    122        @Override
    123        public void init() throws InitializationException
    124        {
    125            setInit(true);
    126        }
    127
    128        /**
    129         * Returns to uninitialized state.
    130         *
    131         * You can use this method to release resources thet your Service
    132         * allocated when Turbine shuts down.
    133         */
    134        @Override
    135        public void shutdown()
    136        {
    137            setInit(false);
    138        }
    139    }