A fixed width, non-serif typeface (sample) indicates the term is a Java package, class, interface, or member name. Text written in this typeface is always related to coding.

Emphasis (sample) is used the first time an important concept is introduced. Its explanation usually follows directly after the introduction.

When an example contains a line that must be broken into multiple lines, the « character is used. Spaces must be ignored in this case. For example:

http://www.acme.com/sp/ «
file?abc=12

is equivalent to:

http://www.acme.com/sp/file?abc=12

In many cases in these specifications, a syntax must be described. This syntax is based on the following symbols:

*           Repetition of the previous element zero or
            more times, e.g. ( ',' element )*
+           Repetition one or more times
?           Previous element is optional
( ... )     Grouping
'...'       Literal
|           Or
[...]       Set (one of)
..          list, e.g. 1..5 is the list 1 2 3 4 5
<...>       Externally defined token
~           Not

The following terminals are pre defined and used throughout the specifications:

ws              ::= <see Character.isWhitespace>
digit           ::= [0..9]
alpha           ::= [a..zA..Z]
alphanum        ::= alpha | digit
token           ::= ( alphanum | '_' | '-' )+
number          ::= digit+
jletter         ::= <see [1] Java Language Specification
                     for JavaLetter>
jletterordigit  ::= <see [1] Java Language Specification
                     for JavaLetterOrDigit>

qname           ::= <see [1] Java Language Specification
                     for fully qualified class names>
identifier      ::= jletter jletterordigit *
extended        ::= ( alphanum | '_' | '-' | '.' )+
quoted-string   ::= '"' ( ~["\#x0D#x0A#x00] | '\"' | '\\' )* '"'
argument        ::= extended  | quoted-string
parameter       ::= directive | attribute
directive       ::= extended ':=' argument
attribute       ::= extended '=' argument

unique-name     ::= identifier ( '.' identifier )*
symbolic-name   ::= token ( '.' token )*
package-name    ::= unique-name

path            ::= special-chars+ | quoted-string
special-chars   ::= ~["\#x0D#x0A#x00:=;,<see [1] Java Language Specification
                                         for whitespace>]

Whitespaces between terminals are ignored unless specifically noted. Any value that contains a space, a comma, colon, semi-colon, equal sign or any other character that is part of a terminal in the grammar must be quoted.

Concepts like classes, interfaces, objects, and services are distinct but subtly different. For example, "LogService" could mean an instance of the class LogService, could refer to the class LogService, or could indicate the functionality of the overall Log Service. Experts usually understand the meaning from the context, but this understanding requires mental effort. To highlight these subtle differences, the following conventions are used.

When the class is intended, its name is spelled exactly as in the Java source code and displayed in a fixed-width typeface: for example, the "HttpService class", "a method in the HttpContext class" or "a javax.servlet.Servlet object". A class name is used in its fully qualified form, like javax.servlet.Servlet, when the package is not obvious from the context, nor is it in one of the well known java packages like java.lang, java.io, java.util and java.net. Otherwise, the package is omitted like in String.

In many cases, a type can be used as a scalar but also a collection of that type or an array of that type. In those cases, a simple + will be suffixed to the type. For example String+, indicates that a String, a String[], and a Collection<String> are all valid forms.

Exception and permission classes are not followed by the word "object". Readability is improved when the "object" suffix is avoided. For example, "to throw a Security Exception" and to "to have File Permission" is more readable then "to have a FilePermission object".

Permissions can further be qualified with their actions. ServicePermission[com.acme.*,GET|REGISTER] means a ServicePermission with the action GET and REGISTER for all service names starting with com.acme. A ServicePermission[Producer|Consumer, REGISTER] means the ServicePermission for the Producer or Consumer class with REGISTER action.

When discussing functionality of a class rather than the implementation details, the class name is written as normal text. This convention is often used when discussing services. For example, "the User Admin service" is more readable.

Some services have the word "Service" embedded in their class name. In those cases, the word "service" is only used once but is written with an upper case S. For example, "the Log Service performs".

Service objects are registered with the OSGi Framework. Registration consists of the service object, a set of properties, and a list of classes and interfaces implemented by this service object. The classes and interfaces are used for type safety and naming. Therefore, it is said that a service object is registered under a class/interface. For example, "This service object is registered under PermissionAdmin."

The diagrams in this document illustrate the specification and are not normative. Their purpose is to provide a high-level overview on a single page. The following paragraphs describe the symbols and conventions used in these diagrams.

Classes or interfaces are depicted as rectangles, as in Figure 1.3. Interfaces are indicated with the qualifier <<interface>> as the first line. The name of the class/interface is indicated in bold when it is part of the specification. Implementation classes are sometimes shown to demonstrate a possible implementation. Implementation class names are shown in plain text. In certain cases class names are abbreviated. This is indicated by ending the abbreviation with a full stop.

Figure 1.3 Class and interface symbol

If an interface or class is used as a service object, it will have a black triangle in the bottom right corner.

Figure 1.4 Service symbol

Service are crucial interaction elements and they can occur many times in diagrams describing services. Therefore, an alternative service symbol is the triangle. Triangles can be connected in different ways, representing different meanings:

Figure 1.5 Alternative Service symbol

Inheritance (the extends or implements keyword in Java class definitions) is indicated with an arrow. Figure 1.6 shows that the AdminPermission class implements or extends the Permission class.

Figure 1.6 Inheritance (implements or extends) symbol

Relations are depicted with a line. The cardinality of the relation is given explicitly when relevant. Figure 1.7 shows that each (1) BundleContext object is related to 0 or more BundleListener objects, and that each BundleListener object is related to a single BundleContext object. Relations usually have some description associated with them. This description should be read from left to right and top to bottom, and includes the classes on both sides. For example: "A BundleContext object delivers bundle events to zero or more BundleListener objects."

Figure 1.7 Relations symbol

Associations are depicted with a dashed line. Associations are between classes, and an association can be placed on a relation. For example, "every ServiceRegistration object has an associated ServiceReference object." This association does not have to be a hard relationship, but could be derived in some way.

When a relationship is qualified by a name or an object, it is indicated by drawing a dotted line perpendicular to the relation and connecting this line to a class box or a description. Figure 1.8 shows that the relationship between a UserAdmin class and a Role class is qualified by a name. Such an association is usually implemented with a Dictionary or Map object.

Figure 1.8 Associations symbol

Bundles are entities that are visible in normal application programming. For example, when a bundle is stopped, all its services will be unregistered. Therefore, the classes/interfaces that are grouped in bundles are shown on a grey rectangle as is shown in Figure 1.9.

Figure 1.9 Bundles

This specification consistently uses the words can, should, and must. Their meaning is well-defined in:

When a specification uses a numbered list, unless otherwise specified, the intention is that the actions described by the items in the list happen in the numerical order of the items. From a Java concurrency point-of-view, this means that the actions described in lower numbered items happens-before the actions described in higher numbered items.