{"action":"created","comment":{"url":"https://api.github.com/repos/akka/akka/pulls/comments/50247230","id":50247230,"diff_hunk":"@@ -1,12 +1,104 @@\n Akka in OSGi\n ============\n \n+Background\n+----------\n+\n+OSGi_ is a mature packaging and deployment standard for component-based systems. It\n+has similar capabilities as Project Jigsaw (originally scheduled for JDK 1.8), but has far stronger facilities to\n+support legacy Java code. This is to say that while Jigsaw-ready modules require significant changes to most source files\n+and on occasion to the structure of the overall application, OSGi can be used to modularize almost any Java code as far\n+back as JDK 1.2, usually with no changes at all to the binaries.\n+\n+.. _OSGI: http://www.osgi.org/developer\n+\n+These legacy capabilities are OSGi's major strength and its major weakness. The creators of OSGi realized early on that\n+implementors would be unlikely to rush to support OSGi metadata in existing JARs. There were already a handful of new\n+concepts to learn in the JRE and the added value to teams that were managing well with straight J2EE was not obvious.\n+Facilities emerged to \"wrap\" binary JARs so they could be used as bundles, but this functionality was only used in limited\n+situations. An application of the \"80/20 Rule\" here would have that \"80% of the complexity is with 20% of the configuration\",\n+but it was enough to give OSGi a reputation that has stuck with it to this day.\n+\n+This document aims to the productivity basics folks need to use it with Akka, the 20% that users need to get 80% of what they want.\n+For more information than is provided here, `OSGi In Action`_ is worth exploring.\n+\n+.. _OSGi In Action: https://www.manning.com/books/osgi-in-action\n+\n+Core Components and Structure of OSGi Applications\n+--------------------------------------------------\n+\n+The fundamental unit of deployment in OSGi is the ``Bundle``. A bundle is a Java JAR with `additional\n+entries <https://www.osgi.org/bundle-headers-reference/>` in ``MANIFEST.MF`` that minimally expose the name and version\n+of the bundle and packages for import and export. Since these manifest entries are ignored outside OSGi deployments,\n+a bundle can interchangeably be used as a JAR in the JRE.\n+\n+When a bundle is loaded, a specialized implementation of the Java ``ClassLoader`` is instantiated for each bundle. Each\n+classloader reads the manifest entries and publishes both capabilities (in the form of the ``Bundle-Exports``) and\n+requirements (as ``Bundle-Imports``) in a container singleton for discovery by other bundles. The process of matching imports to\n+exports across bundles through these classloaders is the process of resolution, one of six discrete steps in the lifecycle\n+FSM of a bundle in an OSGi container:\n+\n+1. INSTALLED: A bundle that is installed has been loaded from disk and a classloader instantiated with its capabilities.\n+   Bundles are iteratively installed manually or through container-specific descriptors. For those familiar with legacy packging\n+   such as EJB, the modular nature of OSGi means that bundles may be used by multiple applications with overlapping dependencies.\n+   By resolving them individually from repositories, these overlaps can be de-duplicated across multiple deployemnts to\n+   the same container.\n+\n+2. RESOLVED: A bundle that has been resolved is one that has had its requirements (imports) satisfied. Resolution does\n+   mean that a bundle can be started.\n+\n+3. STARTING: A bundle that is started can be used by other bundles. For an otherwise complete application closure of\n+   resolved bundles, the implication here is they must be started in the order directed by a depth-first search for all to\n+   be started. When a bundle is starting, any exposed lifecycle interfaces in the bundle are called, giving the bundle\n+   the opportunity to start its own service endpoints and threads.\n+\n+4. ACTIVE: Once a bundle's lifecycle interfaces return without error, a bundle is marked as active.\n+\n+5. STOPPING: A bundle that is stopping is in the process of calling the bundle's stop lifecycle and transitions back to\n+   the RESOLVED state when complete. Any long running services or threads that were created while STARTING should be shut\n+   down when the bundle's stop lifecycle is called.\n+\n+6. UNINSTALLED: A bundle can only transition to this state from the INSTALLED state, meaning it cannot be uninstalled\n+   before it is stopped.\n+\n+Note the dependency in this FSM on lifecycle interfaces. While there is no requirement that a bundle publishes these\n+interfaces or accepts such callbacks, the lifecycle interfaces provide the semantics of a ``main()`` method and allow\n+the bundle to start and stop long-running services such as REST web services, ActorSystems, Clusters, etc.\n+\n+Secondly, note when considering requirements and capabilities, it's a common misconception to equate these with repository\n+dependencies as might be found in Maven or Ivy. While they provide similar practical functionality, OSGi has several\n+parallel type of dependency (such as Blueprint Services) that cannot be easily mapped to repository capabilities. In fact,\n+the core specification leaves these facilities up to the container in use. In turn, some containers have tooling to generate\n+application load descriptors from repository metadata.\n+\n+Notable Behavior Changes\n+------------------------\n+\n+Combined with understanding the bundle lifecycle, the OSGi developer must pay attention to sometimes unexpected behaviors\n+that are introduced. These are generally within the JVM specification, but are unexpected and can lead to frustration.\n+\n+* Bundles should not export overlapping package spaces. It is not uncommon for legacy JVM frameworks to expect plugins\n+  in an application composed of multiple JARs to reside under a single package name. For example, a frontend application\n+  might scan all classes from ``com.example.plugins`` for specific service implementations with that package existing in\n+  several contributed JARs.\n+\n+  While it is possible to support overlapping packages with complex manifest headers, it's much better to use non-overlapping\n+  package spaces and facilities such as `Akka Cluster`_\n+  for service discovery. Stylistically, many organizations opt to use the root package path as the name of the bundle\n+  distribution file.\n+\n+.. _Akka Cluster: @github@/akka-docs/rst/scala/code/docs/akka/current/common/cluster.html","path":"akka-docs/rst/additional/osgi.rst","position":90,"original_position":90,"commit_id":"01faf6772d551739e8aa7050e5dd093be768fd0f","original_commit_id":"01faf6772d551739e8aa7050e5dd093be768fd0f","user":{"login":"patriknw","id":336161,"avatar_url":"https://avatars.githubusercontent.com/u/336161?v=3","gravatar_id":"","url":"https://api.github.com/users/patriknw","html_url":"https://github.com/patriknw","followers_url":"https://api.github.com/users/patriknw/followers","following_url":"https://api.github.com/users/patriknw/following{/other_user}","gists_url":"https://api.github.com/users/patriknw/gists{/gist_id}","starred_url":"https://api.github.com/users/patriknw/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/patriknw/subscriptions","organizations_url":"https://api.github.com/users/patriknw/orgs","repos_url":"https://api.github.com/users/patriknw/repos","events_url":"https://api.github.com/users/patriknw/events{/privacy}","received_events_url":"https://api.github.com/users/patriknw/received_events","type":"User","site_admin":false},"body":"It should be an ordinary rst link","created_at":"2016-01-20T12:17:13Z","updated_at":"2016-01-20T12:17:13Z","html_url":"https://github.com/akka/akka/pull/19435#discussion_r50247230","pull_request_url":"https://api.github.com/repos/akka/akka/pulls/19435","_links":{"self":{"href":"https://api.github.com/repos/akka/akka/pulls/comments/50247230"},"html":{"href":"https://github.com/akka/akka/pull/19435#discussion_r50247230"},"pull_request":{"href":"https://api.github.com/repos/akka/akka/pulls/19435"}}},"pull_request":{"url":"https://api.github.com/repos/akka/akka/pulls/19435","id":55971961,"html_url":"https://github.com/akka/akka/pull/19435","diff_url":"https://github.com/akka/akka/pull/19435.diff","patch_url":"https://github.com/akka/akka/pull/19435.patch","issue_url":"https://api.github.com/repos/akka/akka/issues/19435","number":19435,"state":"closed","locked":false,"title":"=osgi #19323 Add to documentation on OSGi","user":{"login":"briantopping","id":158115,"avatar_url":"https://avatars.githubusercontent.com/u/158115?v=3","gravatar_id":"","url":"https://api.github.com/users/briantopping","html_url":"https://github.com/briantopping","followers_url":"https://api.github.com/users/briantopping/followers","following_url":"https://api.github.com/users/briantopping/following{/other_user}","gists_url":"https://api.github.com/users/briantopping/gists{/gist_id}","starred_url":"https://api.github.com/users/briantopping/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/briantopping/subscriptions","organizations_url":"https://api.github.com/users/briantopping/orgs","repos_url":"https://api.github.com/users/briantopping/repos","events_url":"https://api.github.com/users/briantopping/events{/privacy}","received_events_url":"https://api.github.com/users/briantopping/received_events","type":"User","site_admin":false},"body":"Carryover from #19364, sorry about that, pooched the branch.","created_at":"2016-01-13T23:25:15Z","updated_at":"2016-01-20T12:17:13Z","closed_at":"2016-01-20T10:04:32Z","merged_at":"2016-01-20T10:04:32Z","merge_commit_sha":"66e56431a288b6813ac8d7969f1411b41a9b4442","assignee":null,"milestone":null,"commits_url":"https://api.github.com/repos/akka/akka/pulls/19435/commits","review_comments_url":"https://api.github.com/repos/akka/akka/pulls/19435/comments","review_comment_url":"https://api.github.com/repos/akka/akka/pulls/comments{/number}","comments_url":"https://api.github.com/repos/akka/akka/issues/19435/comments","statuses_url":"https://api.github.com/repos/akka/akka/statuses/01faf6772d551739e8aa7050e5dd093be768fd0f","head":{"label":"briantopping:osgi-doc","ref":"osgi-doc","sha":"01faf6772d551739e8aa7050e5dd093be768fd0f","user":{"login":"briantopping","id":158115,"avatar_url":"https://avatars.githubusercontent.com/u/158115?v=3","gravatar_id":"","url":"https://api.github.com/users/briantopping","html_url":"https://github.com/briantopping","followers_url":"https://api.github.com/users/briantopping/followers","following_url":"https://api.github.com/users/briantopping/following{/other_user}","gists_url":"https://api.github.com/users/briantopping/gists{/gist_id}","starred_url":"https://api.github.com/users/briantopping/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/briantopping/subscriptions","organizations_url":"https://api.github.com/users/briantopping/orgs","repos_url":"https://api.github.com/users/briantopping/repos","events_url":"https://api.github.com/users/briantopping/events{/privacy}","received_events_url":"https://api.github.com/users/briantopping/received_events","type":"User","site_admin":false},"repo":{"id":36791219,"name":"akka","full_name":"briantopping/akka","owner":{"login":"briantopping","id":158115,"avatar_url":"https://avatars.githubusercontent.com/u/158115?v=3","gravatar_id":"","url":"https://api.github.com/users/briantopping","html_url":"https://github.com/briantopping","followers_url":"https://api.github.com/users/briantopping/followers","following_url":"https://api.github.com/users/briantopping/following{/other_user}","gists_url":"https://api.github.com/users/briantopping/gists{/gist_id}","starred_url":"https://api.github.com/users/briantopping/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/briantopping/subscriptions","organizations_url":"https://api.github.com/users/briantopping/orgs","repos_url":"https://api.github.com/users/briantopping/repos","events_url":"https://api.github.com/users/briantopping/events{/privacy}","received_events_url":"https://api.github.com/users/briantopping/received_events","type":"User","site_admin":false},"private":false,"html_url":"https://github.com/briantopping/akka","description":"Akka Project","fork":true,"url":"https://api.github.com/repos/briantopping/akka","forks_url":"https://api.github.com/repos/briantopping/akka/forks","keys_url":"https://api.github.com/repos/briantopping/akka/keys{/key_id}","collaborators_url":"https://api.github.com/repos/briantopping/akka/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/briantopping/akka/teams","hooks_url":"https://api.github.com/repos/briantopping/akka/hooks","issue_events_url":"https://api.github.com/repos/briantopping/akka/issues/events{/number}","events_url":"https://api.github.com/repos/briantopping/akka/events","assignees_url":"https://api.github.com/repos/briantopping/akka/assignees{/user}","branches_url":"https://api.github.com/repos/briantopping/akka/branches{/branch}","tags_url":"https://api.github.com/repos/briantopping/akka/tags","blobs_url":"https://api.github.com/repos/briantopping/akka/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/briantopping/akka/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/briantopping/akka/git/refs{/sha}","trees_url":"https://api.github.com/repos/briantopping/akka/git/trees{/sha}","statuses_url":"https://api.github.com/repos/briantopping/akka/statuses/{sha}","languages_url":"https://api.github.com/repos/briantopping/akka/languages","stargazers_url":"https://api.github.com/repos/briantopping/akka/stargazers","contributors_url":"https://api.github.com/repos/briantopping/akka/contributors","subscribers_url":"https://api.github.com/repos/briantopping/akka/subscribers","subscription_url":"https://api.github.com/repos/briantopping/akka/subscription","commits_url":"https://api.github.com/repos/briantopping/akka/commits{/sha}","git_commits_url":"https://api.github.com/repos/briantopping/akka/git/commits{/sha}","comments_url":"https://api.github.com/repos/briantopping/akka/comments{/number}","issue_comment_url":"https://api.github.com/repos/briantopping/akka/issues/comments{/number}","contents_url":"https://api.github.com/repos/briantopping/akka/contents/{+path}","compare_url":"https://api.github.com/repos/briantopping/akka/compare/{base}...{head}","merges_url":"https://api.github.com/repos/briantopping/akka/merges","archive_url":"https://api.github.com/repos/briantopping/akka/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/briantopping/akka/downloads","issues_url":"https://api.github.com/repos/briantopping/akka/issues{/number}","pulls_url":"https://api.github.com/repos/briantopping/akka/pulls{/number}","milestones_url":"https://api.github.com/repos/briantopping/akka/milestones{/number}","notifications_url":"https://api.github.com/repos/briantopping/akka/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/briantopping/akka/labels{/name}","releases_url":"https://api.github.com/repos/briantopping/akka/releases{/id}","created_at":"2015-06-03T08:44:00Z","updated_at":"2016-01-12T15:49:13Z","pushed_at":"2016-01-19T16:40:17Z","git_url":"git://github.com/briantopping/akka.git","ssh_url":"git@github.com:briantopping/akka.git","clone_url":"https://github.com/briantopping/akka.git","svn_url":"https://github.com/briantopping/akka","homepage":"http://akka.io","size":172997,"stargazers_count":0,"watchers_count":0,"language":"Scala","has_issues":false,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":0,"mirror_url":null,"open_issues_count":0,"forks":0,"open_issues":0,"watchers":0,"default_branch":"master"}},"base":{"label":"akka:master","ref":"master","sha":"ec18320d5aea9e47a4295f39f0c3543deb90aa0f","user":{"login":"akka","id":1496237,"avatar_url":"https://avatars.githubusercontent.com/u/1496237?v=3","gravatar_id":"","url":"https://api.github.com/users/akka","html_url":"https://github.com/akka","followers_url":"https://api.github.com/users/akka/followers","following_url":"https://api.github.com/users/akka/following{/other_user}","gists_url":"https://api.github.com/users/akka/gists{/gist_id}","starred_url":"https://api.github.com/users/akka/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/akka/subscriptions","organizations_url":"https://api.github.com/users/akka/orgs","repos_url":"https://api.github.com/users/akka/repos","events_url":"https://api.github.com/users/akka/events{/privacy}","received_events_url":"https://api.github.com/users/akka/received_events","type":"Organization","site_admin":false},"repo":{"id":130013,"name":"akka","full_name":"akka/akka","owner":{"login":"akka","id":1496237,"avatar_url":"https://avatars.githubusercontent.com/u/1496237?v=3","gravatar_id":"","url":"https://api.github.com/users/akka","html_url":"https://github.com/akka","followers_url":"https://api.github.com/users/akka/followers","following_url":"https://api.github.com/users/akka/following{/other_user}","gists_url":"https://api.github.com/users/akka/gists{/gist_id}","starred_url":"https://api.github.com/users/akka/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/akka/subscriptions","organizations_url":"https://api.github.com/users/akka/orgs","repos_url":"https://api.github.com/users/akka/repos","events_url":"https://api.github.com/users/akka/events{/privacy}","received_events_url":"https://api.github.com/users/akka/received_events","type":"Organization","site_admin":false},"private":false,"html_url":"https://github.com/akka/akka","description":"Akka Project","fork":false,"url":"https://api.github.com/repos/akka/akka","forks_url":"https://api.github.com/repos/akka/akka/forks","keys_url":"https://api.github.com/repos/akka/akka/keys{/key_id}","collaborators_url":"https://api.github.com/repos/akka/akka/collaborators{/collaborator}","teams_url":"https://api.github.com/repos/akka/akka/teams","hooks_url":"https://api.github.com/repos/akka/akka/hooks","issue_events_url":"https://api.github.com/repos/akka/akka/issues/events{/number}","events_url":"https://api.github.com/repos/akka/akka/events","assignees_url":"https://api.github.com/repos/akka/akka/assignees{/user}","branches_url":"https://api.github.com/repos/akka/akka/branches{/branch}","tags_url":"https://api.github.com/repos/akka/akka/tags","blobs_url":"https://api.github.com/repos/akka/akka/git/blobs{/sha}","git_tags_url":"https://api.github.com/repos/akka/akka/git/tags{/sha}","git_refs_url":"https://api.github.com/repos/akka/akka/git/refs{/sha}","trees_url":"https://api.github.com/repos/akka/akka/git/trees{/sha}","statuses_url":"https://api.github.com/repos/akka/akka/statuses/{sha}","languages_url":"https://api.github.com/repos/akka/akka/languages","stargazers_url":"https://api.github.com/repos/akka/akka/stargazers","contributors_url":"https://api.github.com/repos/akka/akka/contributors","subscribers_url":"https://api.github.com/repos/akka/akka/subscribers","subscription_url":"https://api.github.com/repos/akka/akka/subscription","commits_url":"https://api.github.com/repos/akka/akka/commits{/sha}","git_commits_url":"https://api.github.com/repos/akka/akka/git/commits{/sha}","comments_url":"https://api.github.com/repos/akka/akka/comments{/number}","issue_comment_url":"https://api.github.com/repos/akka/akka/issues/comments{/number}","contents_url":"https://api.github.com/repos/akka/akka/contents/{+path}","compare_url":"https://api.github.com/repos/akka/akka/compare/{base}...{head}","merges_url":"https://api.github.com/repos/akka/akka/merges","archive_url":"https://api.github.com/repos/akka/akka/{archive_format}{/ref}","downloads_url":"https://api.github.com/repos/akka/akka/downloads","issues_url":"https://api.github.com/repos/akka/akka/issues{/number}","pulls_url":"https://api.github.com/repos/akka/akka/pulls{/number}","milestones_url":"https://api.github.com/repos/akka/akka/milestones{/number}","notifications_url":"https://api.github.com/repos/akka/akka/notifications{?since,all,participating}","labels_url":"https://api.github.com/repos/akka/akka/labels{/name}","releases_url":"https://api.github.com/repos/akka/akka/releases{/id}","created_at":"2009-02-16T12:51:54Z","updated_at":"2016-01-20T11:22:39Z","pushed_at":"2016-01-20T11:30:10Z","git_url":"git://github.com/akka/akka.git","ssh_url":"git@github.com:akka/akka.git","clone_url":"https://github.com/akka/akka.git","svn_url":"https://github.com/akka/akka","homepage":"http://akka.io","size":182361,"stargazers_count":4987,"watchers_count":4987,"language":"Scala","has_issues":true,"has_downloads":true,"has_wiki":false,"has_pages":false,"forks_count":1518,"mirror_url":null,"open_issues_count":857,"forks":1518,"open_issues":857,"watchers":4987,"default_branch":"master"}},"_links":{"self":{"href":"https://api.github.com/repos/akka/akka/pulls/19435"},"html":{"href":"https://github.com/akka/akka/pull/19435"},"issue":{"href":"https://api.github.com/repos/akka/akka/issues/19435"},"comments":{"href":"https://api.github.com/repos/akka/akka/issues/19435/comments"},"review_comments":{"href":"https://api.github.com/repos/akka/akka/pulls/19435/comments"},"review_comment":{"href":"https://api.github.com/repos/akka/akka/pulls/comments{/number}"},"commits":{"href":"https://api.github.com/repos/akka/akka/pulls/19435/commits"},"statuses":{"href":"https://api.github.com/repos/akka/akka/statuses/01faf6772d551739e8aa7050e5dd093be768fd0f"}}}}