001/**
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *      http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.activemq;
018
019import java.io.InputStream;
020import java.io.OutputStream;
021import java.util.Map;
022
023import javax.jms.Connection;
024import javax.jms.Destination;
025import javax.jms.InvalidDestinationException;
026import javax.jms.JMSException;
027import javax.jms.Topic;
028
029/**
030 * The StreamConnection interface allows you to send and receive data from a
031 * Destination in using standard java InputStream and OutputStream objects. It's
032 * best use case is to send and receive large amounts of data that would be to
033 * large to hold in a single JMS message.
034 * 
035 * 
036 */
037public interface StreamConnection extends Connection {
038
039    InputStream createInputStream(Destination dest) throws JMSException;
040
041    InputStream createInputStream(Destination dest, String messageSelector) throws JMSException;
042
043    InputStream createInputStream(Destination dest, String messageSelector, boolean noLocal) throws JMSException;
044
045    InputStream createInputStream(Destination dest, String messageSelector, boolean noLocal, long timeout) throws JMSException;
046
047    InputStream createDurableInputStream(Topic dest, String name) throws JMSException;
048
049    InputStream createDurableInputStream(Topic dest, String name, String messageSelector) throws JMSException;
050
051    InputStream createDurableInputStream(Topic dest, String name, String messageSelector, boolean noLocal) throws JMSException;
052    
053    InputStream createDurableInputStream(Topic dest, String name, String messageSelector, boolean noLocal, long timeout) throws JMSException;
054
055    OutputStream createOutputStream(Destination dest) throws JMSException;
056
057    OutputStream createOutputStream(Destination dest, Map<String, Object> streamProperties, int deliveryMode, int priority, long timeToLive) throws JMSException;
058
059    /**
060     * Unsubscribes a durable subscription that has been created by a client.
061     * <P>
062     * This method deletes the state being maintained on behalf of the
063     * subscriber by its provider.
064     * <P>
065     * It is erroneous for a client to delete a durable subscription while there
066     * is an active <CODE>MessageConsumer </CODE> or
067     * <CODE>TopicSubscriber</CODE> for the subscription, or while a consumed
068     * message is part of a pending transaction or has not been acknowledged in
069     * the session.
070     * 
071     * @param name the name used to identify this subscription
072     * @throws JMSException if the session fails to unsubscribe to the durable
073     *                 subscription due to some internal error.
074     * @throws InvalidDestinationException if an invalid subscription name is
075     *                 specified.
076     * @since 1.1
077     */
078    void unsubscribe(String name) throws JMSException;
079}