Welo

Welo is a library to work with resources in a general framework. It deals with the following concerns:

- relationships between resources
- structuring and access control with perspectives: one may or may not be able to access all fields of a resource
- identifiers and epithets
- serialization of resources

Perspectives

When you look at a house, you usually can see walls, windows, a door, and a roof. If you can enter the house, then you will see rooms, furniture, inhabitants and so on. Depending on the room where you are, you will not see the roof. The concept of perspective is basically that: depending on where you look from (or who you are), you cannot observe the same parts of the same object. Perspectives have a name, and a set of symbols which corresponds to what someone can observe through this perspective.

A piece of code for the above example could be:

class House

include Welo::Resource
perspective :outside, [:walls, :windows, :roof, :door]
perspective :inside, [:rooms, :furniture, :inhabitants]

end

Identifiers

Say you have a lots of shirts, and picked one for a party. A close friend calls you and ask you which clothes you’re taking. Then, you’ll describe your shirt like “the black shirt with vertical stripes”. You’ve just identified your shirt, by, giving enough information to uniquelly identify a shirt. Then, depending on the situation, you may identify a shirt differently. As an example, the shop where you’ve bought your shirt has a reference number, and maybe a barcode to identify it. By default, Welo will add a ‘uuid’ method (which is aliased to the object_id) for identifying a resource. You can always override that.

class Shirt

include Welo::Resource
# identify :default, :uuid #what Welo does for you
identify :friend, :colors, :stripes, :length
identify :shop, :refnum

end

Relationships

Often, two things are related whith each other. With respect to the state of the art. So far, a person may have many shirts but has only two biological parents: a father and a mother. Currently, Welo has relationships of :one and :many kinds of relationships. This allow you to define some elaborate structures:

class Person

include Welo::Resource
relationship :shirts, :Shirt, :many
relationship :father, :Person, :one
relationship :mother, :Person, :one

end

Someone used to relational system may notice that we only wrote one part of the relationships: if a person has another Person as a parent, therefore, the parents should have a sort of symmetrical relationship. For simplicity, Welo does not force you to write this symmetry relationship if you will not be using it in your program. Similarly, for now, there are no complex associations, like through associations. Welo’s goal is not to build an ORM which optimizes SQL queries.

Finally, there are two ways to qualify relationships: Nestings and Epithets. These two qualifiers are related to the various ways of identifying related resources.

Nesting

Nestings, let you use an external way of identifying a resource. In that case, the resource identification’s scheme depends on the resources, but the value of the identification is within the nested resource itself. As an example, for a company, an employee will be identified upon its social security number, whereas, in a pub, friends will use his name. Nesting, just mark a preferred way of identifying related resources.

class Person

include Welo::Resource
identify :friend, :name
identify :company, :ssn
relationship :friends, :Person, :many
nesting :friends, :friend

end

class Company

include Welo::Resource
relationship :employees, :Person, :many
nesting :employees, :company

end

Epithets

Epithets are similar to nestings, but the way of identifying a resource is only related to the pointing resource. As an example, a person may have three preferred movies. This naming scheme is only personal to the person, but not to the movies. So, if you know that an object has preferred movies, you don’t need to know anything about the movie to identify it within the context of a person. For now, declaring requires you must first specify that the matching relationship is a mere alias, then declare the epithet’s method for identifying the related resource.

class Movie

include Welo::Resource

end

class Person

include Welo::Resource
relationship :preferred_movies, :Movie, :many, :alias
epithet :preferred_movies, :rank_for_preffered_movie

def rank_for_preffered_movie(movie)
  @preferred_movies.index(movie)
end

end

Coming later

• Embedding (similar to mongo’s embedded documents).

• ResourceProxys to manipulate distant resources, or resources observed from one perspective, with missing fields.