What is?

Privacy is a method for users to block communications from particular other users. In XMPP this is done by managing one's privacy lists.
Server-side privacy lists enable successful completion of the following use cases:

• Retrieving one's privacy lists.
• Adding, removing, and editing one's privacy lists.
• Setting, changing, or declining active lists.
• Setting, changing, or declining the default list (i.e., the list that is active by default).
• Allowing or blocking messages based on JID, group, or subscription type (or globally).
• Allowing or blocking inbound presence notifications based on JID, group, or subscription type (or globally).
• Allowing or blocking outbound presence notifications based on JID, group, or subscription type (or globally).
• Allowing or blocking IQ stanzas based on JID, group, or subscription type (or globally).
• Allowing or blocking all communications based on JID, group, or subscription type (or globally).

How can I use it?

The API implementation releases three main public classes:

• PrivacyListManager: this is the main API class to retrieve and handle server privacy lists.
• PrivacyList: witch represents one privacy list, with a name, a set of privacy items. For example, the list with visible or invisible.
• PrivacyItem: block or allow one aspect of privacy. For example, to allow my friend to see my presence.

1. Right from the start, a client MAY get his/her privacy list that is stored in the server:
   

   	// Create a privacy manager for the current connection.
   	PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
   	// Retrieve server privacy lists
   	PrivacyList[] lists = privacyManager.getPrivacyLists();
   

   Now the client is able to show every PrivacyItem of the server and also for every list if it is active, default or none of them. The client is a listener of privacy changes.
   
   
2. In order to add a new list in the server, the client MAY implement something like:

   	// Set the name of the list
   	String listName = "newList";
   
   	// Create the list of PrivacyItem that will allow or deny some privacy aspect
   	String user = "tybalt@example.com";
   	String groupName = "enemies";
   	ArrayList privacyItems = new ArrayList();
   
   	PrivacyItem item = new PrivacyItem(PrivacyRule.JID, true, 1);
   	item.setValue(user);
   	privacyItems.add(item);
   
   	item = new PrivacyItem(PrivacyRule.SUBSCRIPTION, true, 2);
   	item.setValue(PrivacyRule.SUBSCRIPTION_BOTH);
   	privacyItems.add(item);
        	
   	item = new PrivacyItem(PrivacyRule.GROUP, false, 3);
   	item.setValue(groupName);
   	item.setFilterMessage(true);
   	privacyItems.add(item);
   
   	// Get the privacy manager for the current connection.
   	PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
   	// Create the new list.
   	privacyManager.createPrivacyList(listName, Arrays.asList(privacyItems));
   

3. To modify an existent list, the client code MAY be like:

   	// Set the name of the list
   	String listName = "existingList";
   	// Get the privacy manager for the current connection.
   	PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
   	// Sent the new list to the server.
   	privacyManager.updatePrivacyList(listName, items);
   

   Notice items was defined at the example 2 and MUST contain all the elements in the list (not the "delta").
4. In order to delete an existing list, the client MAY perform something like:

   	// Set the name of the list
   	String listName = "existingList";
   	// Get the privacy manager for the current connection.
   	PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
   	// Remove the list.
   	privacyManager.deletePrivacyList(listName);
   

5. In order to decline the use of an active list, the client MAY perform something like:

   	// Get the privacy manager for the current connection.
   	PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
   	// Decline the use of the active list.
   	privacyManager.declineActiveList();
   

6. In order to decline the use of a default list, the client MAY perform something like:

   	// Get the privacy manager for the current connection.
   	PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
   	// Decline the use of the default list.
   	privacyManager.declineDefaultList();
   

Listening for Privacy Changes

In order to handle privacy changes, clients SHOULD listen manager's updates. When a list is changed the manager notifies every added listener. Listeners MUST implement the PrivacyListListener interface. Clients may need to react when a privacy list is modified. The PrivacyListManager lets you add listerners that will be notified when a list has been changed. Listeners should implement the PrivacyListListener interface.
The most important notification is updatedPrivacyList that is performed when a privacy list changes its privacy items.
The listener becomes notified after performing:

	// Get the privacy manager for the current connection.
	PrivacyListManager privacyManager = PrivacyListManager.getInstanceFor(myConnection);
	// Add the listener (this) to get notified
	privacyManager.addListener(this);

References

• Blocking communication from the RFC3921.