Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision		 Previous revision
docs:3500:0400:0410:0412 [2023/04/05 06:25] – removed - external edit (Unknown date) 127.0.0.1docs:3500:0400:0410:0412 [2025/06/12 04:00] (current) – Change to AwareIM aware_support3
Line 1: Line 1:
 +{{tag>Programmers_Reference Custom_channels Source_And_Sink Write_Source example}}
 +[<10>]
 +==== Writing a Source ====
 +
 +Before writing a Source you need to decide the type of Source that will receive messages from your software system or a hardware device. Three types of Sources are supported by the ''openadaptor'' framework:
 +
 +  - //Polling// - the Source of this type will periodically poll a resource looking for data and messages that need to be processed or sent, e.g. a database, a file system or queue-based middleware.
 +  - //Listening //- the Source of this type will wait for a connection, establish a connection and listen, e.g. a socket.
 +  - //Callback //- the Source of this type will register for events and receive call-backs, e.g. publish/subscribe middleware.
 +You must decide which is the most appropriate type of Source for your situation. Depending on which implementation you choose, you will need to implement different methods.
 +
 +After you decide which Source type you will use follow the steps below:
 +
 +  - Inherit your class implementing the Source from the ''AbstractSimpleSource'' class.
 +  - Override the init method to set the Source type and/or initialise the Source with some specific properties. The Source-specific properties would have been entered by the user in the Configuration Tool (see also section 4.3) The type of the Source is set using the following method:<code java>setSourceType(POLL_SOURCE); or
 +setSourceType(LISTEN_SOURCE); or
 +setSourceType(CALLBACK_SOURCE); or</code>
 +  - Depending on the Source type override the following methods:
 +    - For polling Source - <code java>public DataObject[] sourcePoll() throws IbafException</code> This method should return an array of ''DataObjects'' (or ''null'' if there is no data to process at the moment). 
 +    - For listening Source - <code java>public void sourceListen() 
 +throws IbafException</code> This method should call the following method when it has some ''DataObjects'' to process:<code java>sourceProcess(DataObject[] dobs)</code>
 +    - For call-back Source – You will need to implement the third party call-back method. This method should call the following method when it has some DataObject’s to process:<code java>sourceProcess(DataObject[] dobs)</code> In the methods above you need to construct the appropriate ''DataObjects'', which will be delivered to //**AwareIM**// by the framework. To construct the DataObject’s you can use the [[docs:3500:0400:0410:0415|MessageBuilder]] class as shown in the example below.
 +  - You should implement the following method to perform any necessary "start up", such as establishing connections, registering call-backs, etc: <code java> public void sourceStartUp() 
 +throws IbafException</code>
 +  - You should implement the following method to perform necessary "clean up", such as destroying connections, releasing resources, etc:<code java>public void sourceCleanUp() 
 +throws IbafException</code>
 +
 +As an example you can see the code snippet that implements the Source that handles e-mails coming to a mailbox and sends them as notifications to //**AwareIM**//. Note that this code is for illustration purposes only and certain details are omitted.
 +
 +<code java>public  class EmailSource extends AbstractSimpleSource
 +{
 +    private Stringm_mailHost;
 +    private Stringm_userName;
 +    private Stringm_password;
 +    private Sessionm_session;
 +    private Store m_store;
 +    private Folder m_inbox;
 +
 +/** Initializes the source.
 +* Mandatoryproperties
 +* MAIL_HOST_PROPnameofthemailhost,e.g.mail.optus.com
 +* MAIL_USER_PROPnameoftheuser
 +* MAIL_PASSWORD_PROPcredentialsoftheuser
 +* @exception IbafExceptionIfinitializationfails.
 +*/
 +
 +public  void init(Stringname,Propertiesprops,Stringprefix, Controllercontroller)
 +throws IbafException
 +{
 +    try
 +    {
 +        super .init(name,props,prefix,controller);
 +        // set the type of the source!
 +        setSourceType(CALLBACK_SOURCE);
 +        // get different settings that would have been entered// 
 +        // by the user in the Configuration Tool
 +        m_mailHost=props.getProperty(prefix+"."+MAIL_HOST);
 +        if (m_mailHost== null )
 +            throw new IbafException("Mail host property for incoming e-mails is not specified.");
 +        m_userName=props.getProperty(prefix+"."+MAIL_USER);
 +        if (m_userName== null )
 +            throw  new IbafException("User name property is not specified");
 +        m_password=props.getProperty(prefix+"."+ MAIL_PASSWORD);
 +        if (m_password== null )
 +            throw new IbafException("Password property is not specified");
 +        Propertiessettings=System.getProperties();
 +        settings.put("mail.smtp.host",m_mailHost);
 +        settings.put("mail.store.protocol","pop3");
 +        m_session=Session.getInstance(settings, null );
 +        m_store=m_session.getStore();
 +    }
 +    catch (Exceptione)
 +    {
 +        e.printStackTrace();
 +        throw new IbafException(e.getMessage());
 +    }
 +}
 +
 +public  void sourceStartUp()
 +throws IbafException
 +{
 +    super .sourceStartUp();
 +    // try to connect to the remote host
 +    try 
 +    {
 +        connect();
 +    }
 +    catch (Exceptionme)
 +    {
 +    }
 +}
 +
 +public  void sourceCleanUp()
 +throws IbafException
 +{
 +    super .sourceCleanUp();
 +    // close everything
 +    if (m_inbox!= null )
 +    {
 +        synchronized (m_inbox)
 +        {
 +            try 
 +            {
 +                m_inbox.close( false );
 +            }
 +            catch (Exceptione)
 +            {
 +            }
 +        }
 +    }
 +    if (m_store!= null )
 +    {
 +        try 
 +        {
 +            m_store.close();
 +        }
 +        catch (Exceptione)
 +        {  
 +        }
 +    }
 +}
 +/**  connect to the remote host and register our callback function */
 +
 +private  void connect() throws Exception
 +{
 +    try
 +    {
 +        m_store.connect(m_mailHost, 110,m_userName, m_password);
 +    }
 +    catch (Exceptionse)
 +    {
 +    }
 +    // Open a Folder
 +    try 
 +    {
 +        m_inbox=m_store.getFolder("INBOX");
 +    }
 +    catch (Exceptione)
 +    {
 +        throw  new IbafException(e.getMessage());
 +    }
 +    // Register our call back method with the third party API!!
 +    synchronized (m_inbox)
 +    {
 +        m_inbox.addMessageCountListener( new MessageCountAdapter()
 +        {
 +            public  void messagesAdded(MessageCountEventev)
 +            {
 +                gotMessage(ev);
 +            }
 +        });
 +    }
 +}
 +
 +// This is a call-back method that creates data objects */
 +private  void gotMessage(Messagem)
 +{
 +    // create notification of a particular structure
 +    INotificationnotif=DomainFactory.createNotification(DomainFactory.createIncomingEmailNotification());
 +    // set attribute values
 +    try
 +    {
 +        notif.setAttributeValue(INCOMING_EMAIL_MAIL_HOST, m_mailHost);
 +        notif.setAttributeValue(INCOMING_EMAIL_USER_NAME, m_userName);
 +        // etc…
 +        // using MessageBuilder to construct required data 
 +        // objects
 +        MessageBuildermb = new MessageBuilder();
 +        DataObject[]dobs=mb.addNotification( null ,notif);
 +        // send the data objects to AwareIM!
 +        sourceProcess(dobs);
 +    }
 +    catch (Exceptione)
 +    {
 +        // some error handling
 +    }
 +}
 +</code>