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:

  1. 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.
  2. Listening- the Source of this type will wait for a connection, establish a connection and listen, e.g. a socket.
  3. 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:

  1. Inherit your class implementing the Source from the AbstractSimpleSource class.
  2. 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 Implementing Channel Settings Editor) The type of the Source is set using the following method:
    setSourceType(POLL_SOURCE); or
    setSourceType(LISTEN_SOURCE); or
    setSourceType(CALLBACK_SOURCE); or
  3. Depending on the Source type override the following methods:
    1. For polling Source -
      public DataObject[] sourcePoll() throws IbafException

      This method should return an array of DataObjects (or null if there is no data to process at the moment).

    2. For listening Source -
      public void sourceListen() 
      throws IbafException

      This method should call the following method when it has some DataObjects to process:

      sourceProcess(DataObject[] dobs)
    3. 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:
      sourceProcess(DataObject[] dobs)

      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 MessageBuilder class as shown in the example below.

  4. You should implement the following method to perform any necessary “start up”, such as establishing connections, registering call-backs, etc:
    public void sourceStartUp() 
    throws IbafException
  5. You should implement the following method to perform necessary “clean up”, such as destroying connections, releasing resources, etc:
    public void sourceCleanUp() 
    throws IbafException

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.

  1. public class EmailSource extends AbstractSimpleSource
  2. {
  3. private Stringm_mailHost;
  4. private Stringm_userName;
  5. private Stringm_password;
  6. private Sessionm_session;
  7. private Store m_store;
  8. private Folder m_inbox;
  9.  
  10. /** Initializes the source.
  11. * Mandatoryproperties
  12. * MAIL_HOST_PROPnameofthemailhost,e.g.mail.optus.com
  13. * MAIL_USER_PROPnameoftheuser
  14. * MAIL_PASSWORD_PROPcredentialsoftheuser
  15. * @exception IbafExceptionIfinitializationfails.
  16. */
  17.  
  18. public void init(Stringname,Propertiesprops,Stringprefix, Controllercontroller)
  19. throws IbafException
  20. {
  21. try
  22. {
  23. super .init(name,props,prefix,controller);
  24. // set the type of the source!
  25. setSourceType(CALLBACK_SOURCE);
  26. // get different settings that would have been entered//
  27. // by the user in the Configuration Tool
  28. m_mailHost=props.getProperty(prefix+"."+MAIL_HOST);
  29. if (m_mailHost== null )
  30. throw new IbafException("Mail host property for incoming e-mails is not specified.");
  31. m_userName=props.getProperty(prefix+"."+MAIL_USER);
  32. if (m_userName== null )
  33. throw new IbafException("User name property is not specified");
  34. m_password=props.getProperty(prefix+"."+ MAIL_PASSWORD);
  35. if (m_password== null )
  36. throw new IbafException("Password property is not specified");
  37. Propertiessettings=System.getProperties();
  38. settings.put("mail.smtp.host",m_mailHost);
  39. settings.put("mail.store.protocol","pop3");
  40. m_session=Session.getInstance(settings, null );
  41. m_store=m_session.getStore();
  42. }
  43. catch (Exceptione)
  44. {
  45. e.printStackTrace();
  46. throw new IbafException(e.getMessage());
  47. }
  48. }
  49.  
  50. public void sourceStartUp()
  51. throws IbafException
  52. {
  53. super .sourceStartUp();
  54. // try to connect to the remote host
  55. try
  56. {
  57. connect();
  58. }
  59. catch (Exceptionme)
  60. {
  61. }
  62. }
  63.  
  64. public void sourceCleanUp()
  65. throws IbafException
  66. {
  67. super .sourceCleanUp();
  68. // close everything
  69. if (m_inbox!= null )
  70. {
  71. synchronized (m_inbox)
  72. {
  73. try
  74. {
  75. m_inbox.close( false );
  76. }
  77. catch (Exceptione)
  78. {
  79. }
  80. }
  81. }
  82. if (m_store!= null )
  83. {
  84. try
  85. {
  86. m_store.close();
  87. }
  88. catch (Exceptione)
  89. {
  90. }
  91. }
  92. }
  93. /** connect to the remote host and register our callback function */
  94.  
  95. private void connect() throws Exception
  96. {
  97. try
  98. {
  99. m_store.connect(m_mailHost, 110,m_userName, m_password);
  100. }
  101. catch (Exceptionse)
  102. {
  103. }
  104. // Open a Folder
  105. try
  106. {
  107. m_inbox=m_store.getFolder("INBOX");
  108. }
  109. catch (Exceptione)
  110. {
  111. throw new IbafException(e.getMessage());
  112. }
  113. // Register our call back method with the third party API!!
  114. synchronized (m_inbox)
  115. {
  116. m_inbox.addMessageCountListener( new MessageCountAdapter()
  117. {
  118. public void messagesAdded(MessageCountEventev)
  119. {
  120. gotMessage(ev);
  121. }
  122. });
  123. }
  124. }
  125.  
  126. // This is a call-back method that creates data objects */
  127. private void gotMessage(Messagem)
  128. {
  129. // create notification of a particular structure
  130. INotificationnotif=DomainFactory.createNotification(DomainFactory.createIncomingEmailNotification());
  131. // set attribute values
  132. try
  133. {
  134. notif.setAttributeValue(INCOMING_EMAIL_MAIL_HOST, m_mailHost);
  135. notif.setAttributeValue(INCOMING_EMAIL_USER_NAME, m_userName);
  136. // etc…
  137. // using MessageBuilder to construct required data
  138. // objects
  139. MessageBuildermb = new MessageBuilder();
  140. DataObject[]dobs=mb.addNotification( null ,notif);
  141. // send the data objects to AwareIM!
  142. sourceProcess(dobs);
  143. }
  144. catch (Exceptione)
  145. {
  146. // some error handling
  147. }
  148. }