activemq-broker/src/main/java/org/apache/activemq/broker/Broker.java

/**
 * 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.
 */
package org.apache.activemq.broker;

import java.net.URI;
import java.util.Map;
import java.util.Set;
import java.util.concurrent.ThreadPoolExecutor;

import org.apache.activemq.Service;
import org.apache.activemq.broker.region.Destination;
import org.apache.activemq.broker.region.MessageReference;
import org.apache.activemq.broker.region.Region;
import org.apache.activemq.broker.region.Subscription;
import org.apache.activemq.broker.region.virtual.VirtualDestination;
import org.apache.activemq.command.ActiveMQDestination;
import org.apache.activemq.command.BrokerId;
import org.apache.activemq.command.BrokerInfo;
import org.apache.activemq.command.ConnectionInfo;
import org.apache.activemq.command.DestinationInfo;
import org.apache.activemq.command.MessageDispatch;
import org.apache.activemq.command.ProducerInfo;
import org.apache.activemq.command.SessionInfo;
import org.apache.activemq.command.TransactionId;
import org.apache.activemq.store.PListStore;
import org.apache.activemq.thread.Scheduler;
import org.apache.activemq.usage.Usage;

/**
 * The Message Broker which routes messages, maintains subscriptions and
 * connections, acknowledges messages and handles transactions.
 */
public interface Broker extends Region, Service {

    /**
     * Get a Broker from the Broker Stack that is a particular class
     *
     * @param type
     * @return a Broker instance.
     */
    Broker getAdaptor(Class<?> type);

    /**
     * Get the id of the broker
     */
    BrokerId getBrokerId();

    /**
     * Get the name of the broker
     */
    String getBrokerName();

    /**
     * A remote Broker connects
     */
    void addBroker(Connection connection, BrokerInfo info);

    /**
     * Remove a BrokerInfo
     *
     * @param connection
     * @param info
     */
    void removeBroker(Connection connection, BrokerInfo info);

    /**
     * A client is establishing a connection with the broker.
     *
     * @throws Exception TODO
     */
    void addConnection(ConnectionContext context, ConnectionInfo info) throws Exception;

    /**
     * A client is disconnecting from the broker.
     *
     * @param context the environment the operation is being executed under.
     * @param info
     * @param error null if the client requested the disconnect or the error
     *                that caused the client to disconnect.
     * @throws Exception TODO
     */
    void removeConnection(ConnectionContext context, ConnectionInfo info, Throwable error) throws Exception;

    /**
     * Adds a session.
     *
     * @param context
     * @param info
     * @throws Exception TODO
     */
    void addSession(ConnectionContext context, SessionInfo info) throws Exception;

    /**
     * Removes a session.
     *
     * @param context
     * @param info
     * @throws Exception TODO
     */
    void removeSession(ConnectionContext context, SessionInfo info) throws Exception;

    /**
     * Adds a producer.
     *
     * @param context the environment the operation is being executed under.
     * @throws Exception TODO
     */
    @Override
    void addProducer(ConnectionContext context, ProducerInfo info) throws Exception;

    /**
     * Removes a producer.
     *
     * @param context the environment the operation is being executed under.
     * @throws Exception TODO
     */
    @Override
    void removeProducer(ConnectionContext context, ProducerInfo info) throws Exception;

    /**
     * @return all clients added to the Broker.
     * @throws Exception TODO
     */
    Connection[] getClients() throws Exception;

    /**
     * @return all destinations added to the Broker.
     * @throws Exception TODO
     */
    ActiveMQDestination[] getDestinations() throws Exception;

    /**
     * return a reference destination map of a region based on the destination type
     *
     * @param destination
     *
     * @return destination Map
     */
    public Map<ActiveMQDestination, Destination> getDestinationMap(ActiveMQDestination destination);

    /**
     * Gets a list of all the prepared xa transactions.
     *
     * @param context transaction ids
     * @return array of TransactionId values
     * @throws Exception TODO
     */
    TransactionId[] getPreparedTransactions(ConnectionContext context) throws Exception;

    /**
     * Starts a transaction.
     *
     * @param context
     * @param xid
     * @throws Exception TODO
     */
    void beginTransaction(ConnectionContext context, TransactionId xid) throws Exception;

    /**
     * Prepares a transaction. Only valid for xa transactions.
     *
     * @param context
     * @param xid
     * @return id
     * @throws Exception TODO
     */
    int prepareTransaction(ConnectionContext context, TransactionId xid) throws Exception;

    /**
     * Rollsback a transaction.
     *
     * @param context
     * @param xid
     * @throws Exception TODO
     */
    void rollbackTransaction(ConnectionContext context, TransactionId xid) throws Exception;

    /**
     * Commits a transaction.
     *
     * @param context
     * @param xid
     * @param onePhase
     * @throws Exception TODO
     */
    void commitTransaction(ConnectionContext context, TransactionId xid, boolean onePhase) throws Exception;

    /**
     * Forgets a transaction.
     *
     * @param context
     * @param transactionId
     * @throws Exception
     */
    void forgetTransaction(ConnectionContext context, TransactionId transactionId) throws Exception;

    /**
     * Get the BrokerInfo's of any connected Brokers
     *
     * @return array of peer BrokerInfos
     */
    BrokerInfo[] getPeerBrokerInfos();

    /**
     * Notify the Broker that a dispatch is going to happen
     *
     * @param messageDispatch
     */
    void preProcessDispatch(MessageDispatch messageDispatch);

    /**
     * Notify the Broker that a dispatch has happened
     *
     * @param messageDispatch
     */
    void postProcessDispatch(MessageDispatch messageDispatch);

    /**
     * @return true if the broker has stopped
     */
    boolean isStopped();

    /**
     * @return a Set of all durable destinations
     */
    Set<ActiveMQDestination> getDurableDestinations();

    /**
     * Add and process a DestinationInfo object
     *
     * @param context
     * @param info
     * @throws Exception
     */
    void addDestinationInfo(ConnectionContext context, DestinationInfo info) throws Exception;

    /**
     * Remove and process a DestinationInfo object
     *
     * @param context
     * @param info
     *
     * @throws Exception
     */
    void removeDestinationInfo(ConnectionContext context, DestinationInfo info) throws Exception;

    /**
     * @return true if fault tolerant
     */
    boolean isFaultTolerantConfiguration();

    /**
     * @return the connection context used to make administration operations on
     *         startup or via JMX MBeans
     */
    ConnectionContext getAdminConnectionContext();

    /**
     * Sets the default administration connection context used when configuring
     * the broker on startup or via JMX
     *
     * @param adminConnectionContext
     */
    void setAdminConnectionContext(ConnectionContext adminConnectionContext);

    /**
     * @return the temp data store
     */
    PListStore getTempDataStore();

    /**
     * @return the URI that can be used to connect to the local Broker
     */
    URI getVmConnectorURI();

    /**
     * called when the brokerService starts
     */
    void brokerServiceStarted();

    /**
     * @return the BrokerService
     */
    BrokerService getBrokerService();

    /**
     * Ensure we get the Broker at the top of the Stack
     *
     * @return the broker at the top of the Stack
     */
    Broker getRoot();

    /**
     * Determine if a message has expired -allows default behaviour to be
     * overriden - as the timestamp set by the producer can be out of sync with
     * the broker
     *
     * @param messageReference
     * @return true if the message is expired
     */
    boolean isExpired(MessageReference messageReference);

    /**
     * A Message has Expired
     *
     * @param context
     * @param messageReference
     * @param subscription (may be null)
     */
    void messageExpired(ConnectionContext context, MessageReference messageReference, Subscription subscription);

    /**
     * A message needs to go the a DLQ
     *
     *
     * @param context
     * @param messageReference
     * @param poisonCause reason for dlq submission, may be null
     * @return true if Message was placed in a DLQ false if discarded.
     */
    boolean sendToDeadLetterQueue(ConnectionContext context, MessageReference messageReference, Subscription subscription, Throwable poisonCause);

    /**
     * @return the broker sequence id
     */
    long getBrokerSequenceId();

    /**
     * called when message is consumed
     * @param context
     * @param messageReference
     */
    void messageConsumed(ConnectionContext context, MessageReference messageReference);

    /**
     * Called when message is delivered to the broker
     * @param context
     * @param messageReference
     */
    void messageDelivered(ConnectionContext context, MessageReference messageReference);

    /**
     * Called when a message is discarded - e.g. running low on memory
     * This will happen only if the policy is enabled - e.g. non durable topics
     * @param context
     * @param sub
     * @param messageReference
     */
    void messageDiscarded(ConnectionContext context, Subscription sub, MessageReference messageReference);

    /**
     * Called when there is a slow consumer
     * @param context
     * @param destination
     * @param subs
     */
    void slowConsumer(ConnectionContext context,Destination destination, Subscription subs);

    /**
     * Called to notify a producer is too fast
     * @param context
     * @param producerInfo
     * @param destination
     */
    void fastProducer(ConnectionContext context,ProducerInfo producerInfo,ActiveMQDestination destination);

    /**
     * Called when a Usage reaches a limit
     * @param context
     * @param destination
     * @param usage
     */
    void isFull(ConnectionContext context,Destination destination,Usage<?> usage);

    void virtualDestinationAdded(ConnectionContext context, VirtualDestination virtualDestination);

    void virtualDestinationRemoved(ConnectionContext context, VirtualDestination virtualDestination);

    /**
     *  called when the broker becomes the master in a master/slave
     *  configuration
     */
    void nowMasterBroker();

    Scheduler getScheduler();

    ThreadPoolExecutor getExecutor();

    void networkBridgeStarted(BrokerInfo brokerInfo, boolean createdByDuplex, String remoteIp);

    void networkBridgeStopped(BrokerInfo brokerInfo);


}