Date: Tue, 19 Mar 2024 02:04:17 -0400 (EDT) Message-ID: <321210239.8651.1710828257055@lyrasis1-roc-mp1> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_8650_819886951.1710828257055" ------=_Part_8650_819886951.1710828257055 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
Messaging is a communication mechanism used to send and receive informat= ion in a manner which allows the senders and receivers to be unaware of the= activities or status of the other parties involved in the exchange. This l= oose coupling is achieved through the use of an intermediary queue or topic= managed by a messaging provider. The messaging provider is responsible for= delivering messages sent by message producers to message consumers. Messag= ing in Fedora is implemented using the Java Messaging Service (= JMS) which is a specification used by many messaging providers that all= ows messages to be sent or received from a queue or topic in a generic fash= ion.
The goal of messaging in Fedora is to provide updates about the activiti= es of the repository as they occur. This allows external applications to mo= nitor and perform actions based on those activities. In order to provide th= e capability for multiple independent clients to receive identical update m= essages simultaneously, an asynchronous publish-and-subscribe model was cho= sen as the default for Fedora's messaging capability. The messages sent usi= ng this model indicate when functions of API-M have been exercised, thus pr= oviding information about every update made to digital objects within the r= epository.
Fedora uses Apache ActiveMQ as its default messaging= provider. While the use of JMS suggests that any messaging provider suppor= ting JMS can replace ActiveMQ, no other providers have been tested. If you = do use Fedora with another JMS-compliant messaging provider, please let us know your results.
Messaging in Fedora is configured primarily through the messaging module= within the fedora.fcfg file. The following parameters, specified as part o= f the messaging module, are required in order to establish a JMS Connection= :
Once a connection is established to the JMS provider, Fedora needs to kn= ow where to publish messages. Two topics are currently available for this p= urpose:
The names of these topics may be changed by specifying new values for th= e name parameter of the apimUpdateMessages and apimAccessMessages datastore= s within the fedora.fcfg file. Changing the names will not alter the messag= es being sent but will send those messages to different destinations.
If a point-to-point messaging model is preferred, the type parameters of= the datastores mentioned above can be changed to "queue", which will resul= t in the messages being placed in a queue of the name specified in the data= store. Queues allow only a single entity to retrieve and process each messa= ge, but they do remove timing dependencies inherent with the publish-and-su= bscribe model (subscribers must register their interest prior to a message = being published in order to receive that message.)
In order to receive the messages that are being sent by Fedora, you will= need to create a message consumer to listen for Fedora's notification mess= ages. To aid in this effort, the Messaging Client was created. To build the= Messaging Client, run the messaging-client Ant target from the source dist= ribution. After the build completes, look in the dist directory for fedora-= messaging-client.zip, which includes all of the jars necessary to use the F= edora Messaging Client. If you are using a messaging provider other than Ac= tiveMQ, you will need to replace the activemq-all jar with the appropriate = jars from your messaging provider of choice.
The Messaging Client was designed to provide a simple Java interface for= receiving messages from Fedora. Some configuration parameters are necessar= y in order for the client to create a connection and listen to the appropri= ate topic or queue. The parameter names here are the same as those listed a= bove for messaging, and the values should be the same as those in your fedo= ra.fcfg file. The topic or queue name(s) on which to listen are also includ= ed as parameters and the value(s) should match those in the fedora.fcfg dat= astores. If you are using ActiveMQ as your JMS and JNDI providers each topi= c or queue will be created for you, otherwise you will need to create desti= nation object(s) in JNDI to match the property values you specify here.
The code below is a simple example of how to use the Messaging Client. T= he JmsMessagingClient constructor includes three required parameters and tw= o optional parameters. The required parameters include the client ID, the M= essagingListener instance, and the connection properties mentioned above. T= he optional parameters include a message selector and flag which determines= whether durable subscribers should be used to listen over the topics liste= d in the properties. More information about each of the available parameter= s can be found in the JmsMessagingClient javadocs.
public = class Example implements MessagingListener { MessagingClient messagingClient; public void start() throws MessagingException { Properties properties =3D new Properties(); properties.setProperty(Context.INITIAL_CONTEXT_FACTORY, "org.apache.activemq.jndi.ActiveMQInitialCon= textFactory"); properties.setProperty(Context.PROVIDER_URL, "tcp://localhost:61616= "); properties.setProperty(JMSManager.CONNECTION_FACTORY_NAME, "Connect= ionFactory"); properties.setProperty("topic.fedora", "fedora.apim.*"); messagingClient =3D new JmsMessagingClient("example1", this, proper= ties, false); messagingClient.start(); } public void stop() throws MessagingException { messagingClient.stop(false); } public void onMessage(String clientId, Message message) { String messageText =3D ""; try { messageText =3D ((TextMessage)message).getText(); } catch(JMSException e) { System.err.println("Error retrieving message text " + e.getMess= age()); } System.out.println("Message received: " + messageText + " from clie= nt " + clientId); } }
A new feature in Fedora version 3.1 is the option to start the JmsMessag= ingClient asynchronously. If you are starting a messaging client only to li= sten for messages on a topic, there is likely no need to wait for that conn= ection to be made before continuing with other processing. Once the connect= ion is made, messages will be passed to your onMessage() method as usual. T= o take advantage of this, simply call jmsMessagingClient.start(false) rathe= r than messagingClient.start() in the example above. Note that if you inten= d to publish messages, you will still need to wait for the connection to co= mplete (i.e. use messagingClient.start()) prior to adding a message to a to= pic or queue.
The content of messages sent by Fedora takes the form of feed entries ba= sed on the Atom Syndication Format. These = messages correspond to API-M method calls, indicating the name of the metho= d, its parameters, return value, and other information about the method. Ea= ch message will be similar to the following example:
<?xm= l version=3D"1.0" encoding=3D"UTF-8"?> <entry xmlns=3D"http://www.w3.org/2005/Atom" xmlns:fedora-types=3D"http://www.fedora.info/definitions/1/0/types/" xmlns:xsd=3D"http://www.w3.org/2001/XMLSchema"> <id>urn:uuid:3773e144-1b63-4dde-8786-464243af9186</id> <updated>2008-04-14T22:35:13.953Z</updated> <author> <name>fedoraAdmin</name> <uri>http://localhost:8080/fedora</uri> </author> <title type=3D"text">purgeObject</title> <category term=3D"demo:5" scheme=3D"fedora-types:pid" label=3D"xsd:str= ing"></category> <category term=3D"purge message" scheme=3D"fedora-types:logMessage" la= bel=3D"xsd:string"></category> <category term=3D"false" scheme=3D"fedora-types:force" label=3D"xsd:bo= olean"></category> <summary type=3D"text">demo:5</summary> <content type=3D"text">2008-04-14T22:35:13.953Z</content> </entry>
The Atom tags in each message will have the following values:
Two properties are included as part of each JMS message produced by Fedo=
ra, primarily for use by message selectors. These two properties are:
By default, Fedora will shut down if it cannot contact your configured A= ctiveMQ broker upon startup. On the other hand, if your external broker shu= ts down after Fedora has successfully established a connection to it, no re= covery or shutdown is performed, meaning that you could lose messages. The = following steps show how to configure a simple store-and-forward ActiveMQ m= essage broker bridge between Fedora (producer broker) and a remote ESB (mes= sage consumer broker) set up as a failover. This means that Fedora wi= ll:
Best Practice
The following configuration is recommended as a best practice in production environments where Fedora messages are a critical part= of the repository workflow.
Install a remote broker, and make sure it can receive messages via TCP. = Start it up, make sure that it runs, binds to the correct address and port.= Maybe even run a few test, to verify that messages arrive and are processe= d. In the example configurations below, the remote broker is bound to 0.0.0= .0 (all interfaces), port 61617.
xbean-spring-=
3.4.3.jar
and spring-context-2.5.6.jar
files into the F=
edora webapp WEB-INF/lib directory. Most spring applications provide these =
jars; if you are using Apache Servicemix as the contai=
ner for your remote broker, they can be found in the SERVICEMIX_HOME/=
lib
directory.activemq.xml
file, put it in FEDOR=
A_HOME/server/config
.=20
<bea= ns xmlns:amq=3D"http://activemq.apache.org/schema/core"> <!-- ActiveMQ JMS Broker configuration --> <amq:broker id=3D"broker" useShutdownHook=3D"false"> <amq:managementContext> <amq:managementContext connectorPort=3D"1093" createConnector=3D"f= alse"/> </amq:managementContext> <!-- Your remote broker, configured with failover --> <amq:networkConnectors> <amq:networkConnector uri=3D"static:(failover:(tcp://0.0.0.0:61617= ))"/> </amq:networkConnectors> <!-- The directory where Fedora will store the ActiveMQ data --> <amq:persistenceAdapter> <amq:amqPersistenceAdapter directory=3D"file:./data/amq"/> </amq:persistenceAdapter> </amq:broker> <!-- Set this to prevent objects from being serialized when passed along to your embedded broker; saves some overhead processin= g --> <bean id=3D"jmsConnectionFactory" class=3D"org.apache.activemq.ActiveM= QConnectionFactory"> <property name=3D"objectMessageSerializationDefered" value=3D"false= "/> </bean> </beans>
<amq= :networkConnectors> <amq:networkConnector uri=3D"static:(failover:(tcp://0.0.0.0:61617))"/= > </amq:networkConnectors>
activemq.xml
file upon startu=
p, create the embedded broker.fedora.fcfg
:=20
<mod= ule role=3D"org.fcrepo.server.messaging.Messaging" class=3D"org.fcrepo.serv= er.messaging.MessagingModule"> <comment>Fedora's Java Messaging Service (JMS) Module</comment&g= t; <param name=3D"enabled" value=3D"true"/> [...]
java.naming.provider.url
parameter:=20
<par= am name=3D"java.naming.provider.url" value=3D"vm://localhost?brokerConfig= =3Dxbean:file:/path/to/fedora_home/server/config/activemq.xml"/>
Configuring an ActiveMQ store-and-forward network of brokers: http://activemq.apache.org/how-do-distribu= ted-queues-work.html
Using the xbean:file
URI to load the ActiveMQ broker config=
uration from a Spring bean config file: http://a=
ctivemq.apache.org/broker-xbean-uri.html