Assignment 4

Due date: Sunday 5/9 by midnight

Your mission: Document the Resource Service Infrastructure of OpenSim.
Extra mission: Write a technical critique of what you see. And contribute back to open source.

This assignment involves both in-code documentation and external, but informal, Web Services documentation. It does not involve coding per-se. But it involves analyzing code and understanding what it does. Like reading a book – make sure to start early, especially if you are not used to this kind of work.

Form of submission: In EEE and/or partially on a Content Management System.

Goals:

· experience web services in the context of a large framework

· practice architectural recovery: “mining” design principles out of code

· practice [informal] web service specifications

Necessary software components:

· All components from previous homework

· Git. (Mandatory this time) Make sure that you install it properly, including your name, email and line endings (very important). Follow the instructions in Github. You don't necessarily need to configure the SSH keys; they are only necessary if you have your own projects in Github. When installing git in Windows, make sure you choose the right line endings (see pictures in Github help).

Note to all students:

There are a few Windows computers the ICS computer lab that have SecondLife version 1.23, Visual Studio and Git already installed; they are the systems with the green markings on the following map of the CS 364 . This may save you some time, but you will learn less.

Preliminaries:

In this homework we are going to target the core of OpenSim, not the addons in the diva distribution. As such, and to make things simpler, clone the opensim repository in a different place than the previous homework:

$ git clone git://opensimulator.org/git/opensim

Task 1 (30 points)

Add comments to the classes assigned to you – see table of documentation assignments. Some of the classes/methods already have some comments, but they need to be revised, cleaned up, and improved greatly. These classes are the core of the resource service infrastructure in OpenSim, it’s what the simulators use to store/retrieve resources. This infrastructure, and the software architecture being used, is documented here: http://beta.opensimulator.org/node/41 Read that!

With respect to the documentation assignments: half of you will be documenting classes/interfaces called IXService and XService, while the other half will be documenting XConnector. It is important to understand that these are different “interfaces” against which developers may develop extensions. IXService and XService are pure interfaces and business logic of the services, respectively; they are independent of any networking protocol, they impose requirements on what the server-side should do. XConnector are “on-the-wire” (network) interfaces: they are the equivalent of Web APIs that you find out there, they impose requirements on how a server-side should do it.

· For those documenting the abstract interfaces and business logic: make sure to focus on that. Document the interface thoroughly, and cross-reference the comments in the class to the comments in the interface – no need to repeat. For the interface definition documentation (i.e. the <summary>), you can use the exact text that I have here on the “Purpose” part: http://beta.opensimulator.org/node/41

· For those documenting the network interfaces: make sure to focus on that, and not on the business logic.

Your comments don’t need to be long and verbose. In fact, they are much better if they are concise and to the point. When commenting, think: what would *you* like to see there?

In order for you to write good comments, you need to understand what the code is doing. You acquire that understanding using a mix of strategies. First, trust that the names of classes and methods are descriptive of what they do – that’s a safe thing to do in this particular set of files. Second, look at the code inside the methods and understand what it does. Finally, find where the classes/methods are being used, and how.

A well documented class should look like this – click on the link on top of that page or see OpenSim/Framework/Communications/RestClient.cs in your IDE.

Here are some guidelines to C# comments.

Form of submission: Once you are done commenting, commit and produce a patch file – that is your submission for this part.

Criteria for assessment:

· How well the comments follow the guidelines (syntax)

· How good the comments are in terms of documenting what users of those classes/methods must know (semantics)

Important: those of you working on the same files, please don’t change the order of the methods in those files, or I may have merge conflicts.

Task 2 (70 points)

(I recommend finishing Task 1 before doing Task 2)

Write informal specifications of the OpenSim Services / Connector Stubs. The goal is to give enough information so that developers can develop their own service infrastructure to serve OpenSim simulators without having to look at OpenSim code. The specification does not need to be as formal as, say, W3C standard specifications. But it needs to be understandable and actionable.

*** You must follow the specification templates that I have for
IAssetService and AssetServiceConnector Stub.

· For those documenting the abstract interfaces and business logic: Note that these abstract interfaces are the single most important contract between OpenSim developers and extenders of OpenSim. They need to be relentlessly well documented. Pay attention to corner cases and details (things being synchronous, asynchronous, cached, not cached, etc etc etc)

· For those documenting the network interfaces: You should describe the information that is sent on the wire. See this beautifully documented set of alternative stubs for OpenSim:
http://code.google.com/p/openmetaverse/w/list
In order to do this, you may need to run OpenSim and connect it to a Robust server infrastructure to which I will send out instructions later. Then add debug/printout statements in parts of the code that will show you exactly how the messages look like.
Alternatively to adding debug messages in the code, you may run a general-purpose packet sniffer like Ethereal (http://www.ethereal.com/).

See instructions for how to run your own simulator connected to the ucigrid03 resource services infrastructure.

Form of submission: If you don’t want the extra credit, you can submit a text document for this part.

Criteria for assessment:

· How good the informal specification is in terms of documenting what developers need to know in order to develop completely new resource service infrastructures for OpenSim worlds (e.g. based on Apache/PHP, IIS/ASP, etc).

Extra Credit 1: (10 points)

Donate your documentation to the community. For task 1, include a license file (BSD or compatible); for task 2, produce the documentation directly on the OpenSim web site at

http://beta.opensimulator.org/

I will give the login credentials in class. Further details about that content management system will be sent out soon.

Extra Credit 2: (20 points)

Write a 1-page technical critique of the OpenSim Resource Service infrastructure. Imagine that you are going to make an assessment of this infrastructure to your co-workers. What is this all about? What are the strengths? What are the weaknesses? What would you do differently? Etc.

Appendix – Documentation Assignments

Student	Documentation Assignment
BENSON, JAMES RICHARD	IAssetService, AssetService
CHILINGARYAN, STEPHAN	AssetServiceConnector
CHUNG, ALEX RYAN	IAvatarService, AvatarService
DAI, ZIMING	AvatarServiceConnector
DANIELSON, JESSE MAYORGA	IPresenceService, PresenceService
DAO, STACEY THUY VI	PresenceServiceConnector
GASKILL, JEFFREY MICHAEL	IUserAccountService, UserAccountService
HEJAZI, SOHRAB	UserAccountServiceConnector
HSU, RYAN CHRISTOPHER	UserAgentServiceConnector
KAUFMAN, SAMUEL JAMES	IUserAgentService, UserAgentService
KIM, ERIC HYUNJIN	IGatekeeperService, GatekeeperService
KIM, GARRETT	GatekeeperServiceConnector
KIM, TAE SUNG	IAuthenticationService, PasswordAuthenticationService (and Base)
LU, PATRICK CHAO-CHENG	AuthenticationServiceConnector
LUTZE, KYLE STEPHEN	IGridService (A), GridService (A) [interface/class defs + RegisterRegion, DeregisterRegion, GetNeighbours, GetRegionFlags]
MERCHANT, MICHAEL IDRIS	IGridService (B), GridService (B) [GetRegionByUUID, GetRegionByPosition, GetRegionByName, GetRegionsByName, GetRegionRange, GetDefaultRegions, GetFallbackRegions]
MORALES, FRANCISCO	GridServiceConnector (A) [interface/class defs + RegisterRegion, DeregisterRegion, GetNeighbours, GetRegionFlags]
MUSLER, KYLE PHILLIP	GridServiceConnector (B) [GetRegionByUUID, GetRegionByPosition, GetRegionByName, GetRegionsByName, GetRegionRange, GetDefaultRegions, GetFallbackRegions]
ONO, HIROE	IFriendsService, FriendsService
PALMER, MATTHEW JAMES	FriendsServiceConnector
PAPA, JOSHUA ALEXANDER	XInventoryConnector (A) [CreateUserInventory, GetInventorySkeleton, GetRootFolder, GetFolderForType, GetFolderContent, GetFolderItems]
WILKINSON, KEVIN MICHAEL	XInventoryConnector (B) [GetFolder, AddFolder, UpdateFolder, MoveFolder, DeleteFolders, PurgeFolder]
WOLK, JORDANIEL CHARLES	XInventoryConnector (C) [AddItem, UpdateItem, MoveItems, DeleteItems, GetItem, GetActiveGestures, GetAssetPermissions]