JBoss.orgCommunity Documentation

Chapter 4. Protocol

4.1. API Overview
4.2. Configuration
4.2.1. M3UAProvider

MTP layer is built with several components. Following list those that may be directly involved in creating application on top of this stack:

org.mobicents.protocols.ss7.mtp.Mtp1

This interface is implemented by classes directly interacting with SS7 hardware. It declares utility methods to open/close underlying implementations and generic read/write methods. It is decalred as follows:



package org.mobicents.protocols.ss7.mtp;
import java.io.IOException;
public interface Mtp1 {
    /**
     * Gets the code of this channel.
     * 
     * @return the code of this channel.
     */
    public int getCode();
    /**
     * Set MTP2 layer serving this MTP1
     * 
     * @param link
     */
    public void setLink(Mtp2 link);
    /**
     * Get MTP2 latyer serving this MTP1
     * 
     * @return
     */
    public Mtp2 getLink();
    /**
     * Reads up to buffer.length bytes from layer 1.
     * 
     * @param buffer
     *            reader buffer
     * @return the number of actualy read bytes.
     */
    public int read(byte[] buffer) throws IOException;
    /**
     * Writes data to layer 1.
     * 
     * @param buffer
     *            the buffer containing data to write.
     * @param bytesToWrite
     */
    public void write(byte[] buffer, int bytesToWrite) throws IOException;
    /**
     * Open message tranfer part layer 1.
     */
    public void open() throws IOException;
    /**
     * Close message tranfer part layer 1.
     */
    public void close();
}
                    
org.mobicents.protocols.ss7.mtp.SelectorFactory

This is simple factory interface with one method: public ChannelSelector getSelector(); . This method returns concrete implementation of interface used for I/O select operations. Implementation is tied directly to layer 1 interface implementation. Concrete factory class should be provide along it.

It is defined as follows:



package org.mobicents.protocols.ss7.mtp;
import java.util.Collection;
public interface ChannelSelector {
    /**
     * Register specfield channel for IO.
     *
     * @param channel the channel to be registered.
     */
    public void register(Mtp1 channel);
    
    /**
     * Unregisters channels
     *
     * @param channel to be unregistered 
     */
    public void unregister(Mtp1 channel);
    
    /**
     * Gets channels ready for IO operations.
     *
     * @param key IO operations.
     * @param timeout the wait timeout.
     */
    public Collection<Mtp1> select(int key, int timeout);
}
                    
org.mobicents.protocols.ss7.mtp.Mtp2

This is concrete implementation of MTP2 layer. It requires Mtp1. It declares following methods, relevant to configuration process:

Mtp2 declares single method for data send operation: public boolean queue(byte[] msg). This method requires properly formed Mtp3 message.

org.mobicents.protocols.ss7.mtp.Mtp3

This is concrete implementation of MTP3 layer. It implements state machine and encoding/decoding rules. It declares following methods, relevant from user point:

MtpUser is defined in following way:



package org.mobicents.protocols.ss7.mtp;
public interface MtpUser {
    /**
     * Callback method from lower layers MTP3-. This is called once MTP3
     * determines that link is stable and is able to send/receive messages
     * properly. This method should be called only once. Every linkup event.
     */
    public void linkUp();
    /**
     * Callback method from MTP3 layer, informs upper layers that link is not
     * operable.
     */
    public void linkDown();
    /**
     * Callback from Layer4+. It expects properly encoded MTP3 message. It forwards data to MTP3
     * @param msgBuff
     */
    public void receive(byte[] msgBuff);
    
    public void setMtp3(Mtp3 mtp);
}
                    
org.mobicents.protocols.ss7.mtp.RoutingLabel

This is utility class used by other layers. It extracts routing label from MTP3 MSU and performs operation to create label ready to be used in answers.

org.mobicents.protocols.ss7.mtp.provider.MtpProvider

This interface defines contract with upper layer protocol stacks. Its concrete implementation is created wtih MtpProviderFactory class. It is defined as follows:



package org.mobicents.protocols.ss7.mtp.provider;
import java.io.IOException;
import java.util.Properties;
import org.mobicents.protocols.ConfigurationException;
import org.mobicents.protocols.StartFailedException;
public interface MtpProvider {
    /**
     * Sets listener for MTP callbacks. If null is passed internal refence is
     * cleared.
     * 
     * @param lst
     */
    public void setMtpListener(MtpListener lst);
    /**
     * Passes argument to MTP layers for processing. Passed buffer should not be
     * reused after passing to this method!
     * 
     * @param msu
     * @throws IOException
     *             - when IO can not be performed, ie, link is not up.
     * @return
     */
    public void send(byte[] msu) throws IOException;
    /**
     * Starts this provider implementation. Depending on internal it can start
     * local MTP process, or M3UA layer.
     * 
     * @throws IOException
     * @throws StartFailedException
     */
    public void start() throws StartFailedException;
    /**
     * Stops this provider. This call clears all references, ie. listener is
     * cleared as {@link #setMtpListener(MtpListener)} with null argument.
     */
    public void stop();
    /**
     * Method which configures concrete classs. Depending on implementation
     * different properties are supported. However each property starts with
     * "mtp." prefix.
     * 
     * @param p
     */
    public void configure(Properties p) throws ConfigurationException;
    /**
     * Checks if link is up;
     * 
     * @return
     */
    public boolean isLinkUp();
}
                    
org.mobicents.protocols.ss7.mtp.provider.MtpListener

This interface defines callback methods which are called from MtpProvider concrete class.

org.mobicents.protocols.ss7.mtp.provider.MtpProviderFactory

Factory class for concrete implementation of MtpProvider. Create method accepts java.util.Properties. It expects mtp.driver property to contain either full class name of concrete implementation of provider or name of supported providers.

Higher protocol layer requires following: