openliberty / docs Goto Github PK
View Code? Open in Web Editor NEWSee Open Liberty documentation on https://openliberty.io/docs/
Home Page: https://openliberty.io/docs/
License: Other
See Open Liberty documentation on https://openliberty.io/docs/
Home Page: https://openliberty.io/docs/
License: Other
From Alasdair:
I know the "Why JSON-B is better than JSON-P" section is yet to be SME-reviewed but @NottyCode gave some feedback I forgot to pass on to you last week that might be relevant when discussing with the SME.
It would be better if the section identified when to use JSON-B and when to use JSON-P, rather than saying one is always better than the other. Both APIs are provided and both have strengths with particular use cases.
For details, see: https://github.ibm.com/was-liberty/liberty-docs/issues/1116
New property was added in 19003. It was not documented because it was added at request from an internal team who know or can work out from the generated config doc how to use it.
If added in future, the whole topic needs to be broken down into reference material with specific common/important tasks as proper task topics - not just appended to this long 14-step topic that contains many optional steps (https://www.ibm.com/support/knowledgecenter/en/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/twlp_config_oidc_rp.html).
There are quite a few server command
documentation files that have Asiidoctor attributes that were copied/pasted from the guide template. These attributes are specifically for guides and cannot be used for the server command
documentation. Please remove the attributes. The attributes prevent the documentation from being rendered properly by Jekyll
.
One example found in server-create.adoc
https://raw.githubusercontent.com/OpenLiberty/docs/develop/ref/commands/server/server-create.adoc
:page-layout: guide
// INSTRUCTION: The project id is the part of the git repository after the guide- and must be specified
:projectid: github repo name without the guide- prefix
// INSTRUCTION: Provide an estimate of how long the guide will take to go through.
:page-duration: 15 minutes
// INSTRUCTION: Provide the date when the guide is published. Format is YYYY-MM-DD.
:page-releasedate: 2017-11-17
// INSTRUCTION: Provide a description for the guide index page.
:page-description: Learn how to create a REST service with JAX-RS, JSON-P, and Open Liberty.
// INSTUCTION: Please provide relevant tags, try to avoid inventing new ones, tags where there is 1 guide for the tag isn't useful.
:page-tags: ['REST', 'Getting Started']
// INSTRUCTION: Specify the unique name of the guide that is used in the permalink. For example below, it is rest-service
:page-related-guides: ['']
// INSTRUCTION: Specify the slug in the website. This must be unique.
:page-permalink: /guides/rest-service
// INSTRUCTION: You should have this to source the common page elements, clone [email protected]:OpenLiberty/guides-common.git
:common-includes: https://raw.githubusercontent.com/OpenLiberty/guides-common/master
// INSTRUCTION: You can't have a new line between the attributes and the title.
// The details of what to fill in for this template are in the comments. So, read the source for this template to see the comments.
//
https://openliberty.io/guides/microprofile-jwt.html
Review guide for concepts/reference material needed to support it.
Identify concept topics.
See existing concept material we might be able to update and use:
https://developer.ibm.com/wasdev/docs/using-access-tokens-secure-microservices/ I think this gives a reasonable explanation of the concept in the first half of this article. The sample is out-of-date because we'd now use MicroProfile so I don't know how much of that is useful or whether we'd need an example when the guide contains that level of detail. Without the sample, it's actually not a bad length.
https://developer.ibm.com/wasdev/docs/using-signed-json-web-tokens-jwts-secure-microservices/ The first part of this article is a duplicate of the previous one (I think he originally wrote them as a single post but I objected to it being so long). Then it explains the concept of JSON Web Tokens (JWT). Again, the sample bit after it probably isn't relevant any more.
Comments from the original author (which may not be relevant to these concept topics, actually; maybe more relevant to if we do further security guides):
they should work fine with open liberty.. The problem with posts like that is they are trying to educate about OAuth2/OIDC/JWT all at once, which requires 2 or 3 services minimum to setup and get going. I don't think I've ever found a great example that pulls off that level of complexity without losing a few people along the way. I mean.. it's not too hard once you understand what each tech is, and how it plays together, but most ppl just want to "make it secure" and come to the problem having used basic auth/forms login with a fixed user db, which just doesn't give you the concepts needed to hang the knowledge off.
As for change.. Ideally I'd love to show Cloud Foundry / K8S with them.. show actual integration to Facebook/Google/KeyCloak to give more context.. but all that was axed to make the existing stuff small enough to explain. (There is a bluemix-sso branch on the https://github.com/WASdev/sample.microservices.security.jwt that I put together a year or two ago to demonstrate some of this for a customer, but it doesn't cover all the bases, just enough for them to get the point)
Liberty KC topics - which, if any?
Identify reference topics.
Identify how/if each should be linked from the guide.
Find SME to help.
Publish.
Is this text suppose to be in the documentation for server pause
command?
NOTE: LC: Can the types be combined in a single command? If so, we should mention it in the descriptions above and give an example in Usage below.
See file:
https://github.com/OpenLiberty/docs/blob/master/ref/commands/server/server-pause.adoc
We need to update the MP Intro document to include JSON-B i.e. update it to reflect the latest in MP 2.x. The REST foundation layer should be updated to include JSON-B in the picture.
When the MP Concurrency feature is GA status, the information proposed by Nathan Rauh to be published as OL docs.
See for details: https://github.ibm.com/was-liberty/liberty-docs/issues/1090
This information will first be published as a blog post on OL.io to mark the availability of the MP Concurrency capability in the OL development builds (ie 'beta' status though we don't call it a beta on OL). When the doc topic(s) is/are published (in OL docs), the blog post URL will be redirected to the doc topic to avoid duplication of content and to so that people with the blog post URL will find the new doc.
https://www.openliberty.io/guides/cdi-intro.html
Review the guide for potential concept and reference topics that a developer would need to adapt the guide app.
Ask Alasdair/Laura/Graham to review list of potential topics to check that they are necessary/useful.
Find sources of the information required to write each topic, inc W/Liberty Knowledge Center, online...
Problem: In the Open Liberty command reference, the text in the main content frame cuts off the text on right-hand side of the frame, and there is no scroll bar to navigate down through the content in that frame. The scroll bar that does appear on the page only moves the TOC and the rest of the page that contains the content frame.
Browser: Firefox 62.0.3 (64-bit)
Example page: https://openliberty.io/docs/ref/command/#server-create.html
In the following screenshot, the circled text runs off the page. The text in the content frame was manually scrolled by dragging the content frame itself, but the scroll bar position corresponds to and controls the position of the TOC (and rest of the page). There is no additionally visible scroll bar that controls the content frame itself.
https://www.openliberty.io/guides/rest-client-java.html
Review the guide for potential concept and reference topics that a developer would need to adapt the guide app.
Ask Alasdair/Laura/Graham to review list of potential topics to check that they are necessary/useful.
Find sources of the information required to write each topic, inc W/Liberty Knowledge Center, online...
We're publishing a blog post about why you don't need to tune Open Liberty (because of its auto-tuning algorithm) which should then be converted to a concept topic in the OL docs.
Blog post is here:
https://openliberty.io/blog/2019/04/03/liberty-threadpool-autotuning.html
There is potentially an argument for the Threading Settings section being a separate reference topic but the whole point is that we don't want to encourage people to changing these settings unless they really need to so I don't think we should have a separate reference topic - they should see this info only in context of the explanatory conceptual info. I could be convinced otherwise but let's start with just a single concept topic, get it reviewed, and then see what feedback we get.
Also (ask Laura), create a redirect from the blog post URL to the new topic when done.
I think this will be part of an "About Open Liberty" or "Open Liberty Architecture" or similar set of topics. @NottyCode is currently investigating what information to include there.
https://openliberty.io/docs/ref/command/#runnablejarfiles.html
Also, there is a dead internal link ('Environment variables').
The Exit Codes and Server Process sections aren't relevant.
cc @NottyCode
Oracle UCP support is targeted to GA in 19.0.0.4. Below is a draft of what this content should look like:
Database connectivity with Oracle UCP
Oracle Universal Connection Pool (UCP) is a standalone JDBC connection pool. When using Oracle UCP with Open Liberty you are using the Oracle UCP connection pool instead of using Open Liberty's built-in connection pooling functionality. Some of Oracle's high availability database functionality requires the use of Oracle UCP. Support for Oracle UCP was added in Open Liberty version 19.0.0.4.
Configuring a Data Source using Oracle UCP
Ensure that one of the JDBC features is enabled in server configuration. Oracle UCP can be used with any version of JDBC supported by Open Liberty, but support for any specific specification functionality will be limited to what is supported by Oracle UCP.
<featureManager>
<feature>jdbc-4.2</feature>
<feature>jndi-1.0</feature> <!-- Required only if JNDI is desired to look up resources -->
</featureManager>
Configure the datasource and library in server config. The UCP driver and Oracle JDBC driver can be obtained from Oracle.
<dataSource id="oracleUCPDS" jndiName="jdbc/oracleUCPDS" >
<jdbcDriver libraryRef="OracleUCPLib" />
<properties.oracle.ucp URL="jdbc:oracle:thin:@//localhost:1521/SAMPLEDB" />
</dataSource>
<library id="OracleUCPLib">
<fileset dir="C:/Oracle/Drivers" includes="ojdbcx.jar ucp.jar"/>
</library>
Note that Oracle UCP might require some properties to be set in the properties.oracle.ucp element, such as the user and password, depending on the version used.
Since the Liberty connection pool is disabled, some of the Open Liberty datasource and connection manager configuration values are ignored and overridden. The following connection manager properties cannot be used with Oracle UCP:
agedTimeout
connectionTimeout
maxIdleTime
maxPoolSize
minPoolSize
purgePolicy
reapTime
maxConnectionsPerThread
maxConnectionsPerThreadLocal
Additionally, the datasource properties statementCacheSize and validationTimeout cannot be used when using UCP with Open Liberty, as Open Liberty's statement caching and connection validation are disabled.
For most of those datasource and connection manager properties, Oracle UCP provides equivalent functionality. See Oracle's documentation for more details and note that some default property values differ between Open Liberty's connection manager and Oracle UCP. The Oracle UCP properties can be applied to the properties.oracle.ucp
properties element.
The dataSource types of ConnectionPoolDataSource and Driver are not supported with Oracle UCP since the UCP driver does not provide an implementation of those interfaces.
The data source can be accessed and utilized by the application using the standard JDBC APIs.
Fault Tolerance 2.0 is going to beta in 19.0.0.2. This task is to update the documentation for OpenLiberty/open-liberty#4078
In addition to the auto-generated feature documentation, please can we update this page: https://www.ibm.com/support/knowledgecenter/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/twlp_microprofile_fault_tolerance.html
I'd suggest the following changes:
mpFaultTolerance-2.0
mpFaultTolerance-x.x
features include concurrent-1.0
so the user should not need to include it themselves.@Asynchronous
which should be inserted between the examples for Retry and Bulkhead.
@Asynchronous
and making the method return a Future
or (FT 2.0 only) CompletionStage
. This functionality can make other fault tolerance annotations more powerful, for example allowing a Bulkhead to queue waiting method calls, or allowing a @Timeout
to return a result as soon as the time limit is reached, even if the method does not respond to being interrupted.Asynchronous code snippet 1: Create an AsynchronousBean with methods which return Future
or CompletionStage
.
@RequestScoped
public class AsynchronousBean {
@Asynchronous
public Future<String> serviceA() {
try {
// Sleep to simulate work
Thread.sleep(3000);
} catch (InterruptedException e) {
throw new RuntimeException("serviceA interrupted", e);
}
// Return the result in a completed CompletableFuture
return CompletableFuture.completedFuture("serviceA OK");
}
// Note: returning a CompletionStage requires Fault Tolerance 2.0
@Asynchronous
public CompletionStage<String> serviceB() {
try {
// Sleep to simulate work
Thread.sleep(3000);
} catch (InterruptedException e) {
throw new RuntimeException("serviceB interrupted", e);
}
// Return the result in a completed CompletableFuture (which implements CompletionStage)
return CompletableFuture.completedFuture("serviceB OK");
}
}
Asynchronous code snippet 2: Use the AsynchronousBean.
@Inject AsynchronousBean asyncBean;
// serviceA and serviceB methods will run in parallel because they are annotated with @Asynchronous
Future<String> resultA = asyncBean.serviceA();
CompletionStage<String> resultB = asyncBean.serviceB();
// The CompletionStage returned from serviceB allows us to add actions which take place when the serviceB method finishes
resultB.thenAccept((r) -> System.out.println("ServiceB result: " + r))
.exceptionally((ex) -> {
System.out.println("ServiceB failed");
ex.printStackTrace();
return null;
});
// For the Future returned from serviceA, we need to wait for it to finish, then we can handle the result
try {
System.out.println("serviceA result: " + resultA.get());
} catch (ExecutionException ex) {
System.out.println("ServiceA failed");
ex.printStackTrace();
} catch (InterruptedException ex) {
System.out.println("Interrupted waiting for serviceA");
}
Complete drafts to make them consistent.
Tech review.
Work with design and web team on a simple page design (we can iterate and refine as we develop more docs and get ideas about presentation) and location under the 'Reference Docs' heading in OpenLiberty.io/docs.
Publish topics.
(Anything else required to publish them?)
https://github.ibm.com/was-liberty/liberty-docs/issues/916
I think this will probably make it into 19.0.0.1. It's already in development builds and was mentioned in a blog post this week (a shorter version than the doc proposed in the issue above): https://openliberty.io/blog/2018/12/20/http-forwarded-header.html
We would like to create a templates
folder that will contain adoc
that help new contributors get started.
Today we already have one template found https://github.com/OpenLiberty/docs/blob/master/ref/commands/server/reference_template.adoc
Some of the work that will need to be done on openliberty.io side is using the exclude
configuration flag to ignore the new templates folder.
Need a tech review and then probably a selective include of the relevant bits of info in each topic.
cc @NottyCode
What is it (relative to a REST service), what makes it RESTful?
Why and where do you use it? Can a service be a client and a service? alternative ways of doing it?
Consuming from your own versus third party service - any differences? (eg all our different Java client guides??)
Describe CRUD - GET, POST, UPDATE, DELETE
We need the guides to link to the docs that support them.
We have:
Docs we're writing, specifically (at the moment) concept docs to support the guides (eg JSON-B/JSON-P concepts to support the https://www.openliberty.io/guides/rest-client-java.html guide.
Generated docs, eg Javadocs for the annotations (in particular) that are used in the guide sample apps; server config doc (not relevant to most of our guides except the Deploying guide).
In both cases, the developer reading the guide (and/or trying to write their own app based on the guide) needs to be able to find this information. But without being swamped with loads of links (or they won't know which ones to click). The links need to be labelled clearly so that they know what they will find (so they can decide whether it's worth clicking it).
We need some simple guidance about what to include as links, what level should be linked to, where the links should be. For instance, I think the guide design includes links to suggested other guides at the bottom. Should there be a sidebar of related links? Or some other pattern? Or just links within the text as appropriate (and what style should that take?)?
https://www.openliberty.io/guides/getting-started.html
Learn about Open Liberty in the context of application development.
Requires:
Installing Maven, Git, Docker.
Do #70 first.
Create new content about Java 11 support in Open Liberty, based on updates from the following liberty-docs issue: https://github.ibm.com/was-liberty/liberty-docs/issues/829
The updates from the previous issue are made in KC. However, for new content, we can publish that content to openliberty.io and link from KC. For example, we need new content about how to enable the kill switch when starting the JVM. That content can be published in the following draft topic (specifically see the Usage section for that content):
https://github.com/OpenLiberty/docs/blob/develop/ref/rol_Java11.adoc
https://docs.docker.com/get-started/
Learn: basic Docker skills.
Then: Work through (or read) the Open Liberty Docker guide (https://www.openliberty.io/guides/docker.html) to understand how a developer can use Docker in their development environment.
To recreate, go to the OL Docs Reference > Server Commands page at https://www.openliberty.io/docs/ref/command/#server-commands.html. Notice that the list of commands in the navigation tree doesn't include package.
The package command info is partly available by going to the Overview at https://www.openliberty.io/docs/ref/command/#server-commands.html and scrolling to the package info:
Package the server
Run the server package command to package a server, its resources, and applications in a ZIP file that you can store, distribute, or deploy to a different location.
server package myserver --include=all
The server package link shows some of the package command info but server-package.adoc
doesn't appear to have been correctly transformed to server-package.html
(see https://www.openliberty.io/docs/ref/command/#server-package.html) and it's missing from the vertical navigation tree.
https://www.openliberty.io/guides/rest-intro.html
Review the guide for potential concept and reference topics that a developer would need to adapt the guide app.
Ask Alasdair/Laura/Graham to review list of potential topics to check that they are necessary/useful.
Find sources of the information required to write each topic, inc W/Liberty Knowledge Center, online...
Fourth of Graham's layers
https://openliberty.io/docs/ref/command/#server-commands.html
I believe we agreed that the 'Usage examples' section should be first. I'm just checking what the rest of the order should be but I think something like this: https://openliberty.io/docs/ref/command/#server-package.html
Not like this: https://openliberty.io/docs/ref/command/#server-create.html
https://www.openliberty.io/guides/rest-intro.html
Learn basic Maven skills and how developers write a simple web service with tests and deploy it to Open Liberty.
Requires installing Maven and Git on laptop.
To help with the new server command doc page in the openliberty.io site, the following updates to the asciidoc are required:
add
page-layout: server-command
to the following files:
runnablejarfiles.adoc, server-commands.adoc, server-create.adoc, server-debug.adoc, server-dump.adoc, server-exitcodes.adoc, server-help.adoc, server-javadump.adoc, server-list.adoc, server-package.adoc, server-pause.adoc, server-resume.adoc, server-run.adoc, server-serverprocess.adoc, server-start.adoc, server-stop.adoc, and server-version.adoc
The page-layout attribute is the name of the layout used to format the doc.
add
page-type: overview
to server-commands.adoc
add
page-type: command
to server-create.adoc, server-debug.adoc, server-dump.adoc, server-help.adoc, server-javadump.adoc, server-list.adoc, server-package.adoc, server-pause.adoc, server-resume.adoc, server-run.adoc, server-start.adoc, server-stop.adoc, and server-version.adoc
add
page-type: reference
to runnablejarfiles.adoc, server-exitcodes.adoc, and server-serverprocess.adoc
The page-type attribute is to use for grouping. There are three types in the server command. They are command (that would appear in the table of content), overview (which is an overview doc that appears in the table of content), and reference (that appears in the doc content but would not appear in the table of content).
In addition, the following fixes have to be made:
server-debug.adoc should have a title of "server debug command" not "server package command"
server-resume.adoc: remove the following 2 lines
In the Server Config logging
OL docs (https://openliberty.io/docs/ref/config/#logging.html), which is generated from the build, is a table of attributes that can be used in the server configuration (eg server.xml
file). However, in the KC there is also a (manually created) topic that includes a similar (but not identical) table of the attributes. We don't need this duplication of reference information as there's no benefit and unnecessary maintenance. However, there is additional information in the KC topic that is not in the generated logging
OL topic. So we need to update the generated doc so it is more useful.
logging
OL topic (including the information in the 'Equivalent property' column).logging
OL topic with that information.logging
OL topic to make the table more understandable (currently says only "Controls the capture and output of log and trace messages."):
Talk to Don Bourne (or Alasdair/Laura) about how to get the #logging.html
topic updated with the missing info.
https://openliberty.io/docs/ref/command/server-package.html
The stylesheet isn't applied properly. Also, it's not appearing in the ToC:
(I haven't checked but I guess there might be others the same?)
I'm linking to the server package
command page from 18004 blog post.
Introduce logging and tracing in Open Liberty. Including...
But don't include the 'Logging properties for the Liberty component. ' table from the KC topic because it duplicates info in the 'logging' config doc (https://openliberty.io/docs/ref/config/#logging.html). See #195 for what to do with that.
Background:
https://openliberty.io/guides/getting-started.html#checking-the-open-liberty-server-logs
Contact:
Alasdair Nottingham?
To be published at this URL: https://openliberty.io/docs/ref/feature/
Similar to https://openliberty.io/docs/ref/config/
Compile from information throughout the KC. Discuss with @NottyCode who has started looking at this.
This is required by issue OpenLiberty/openliberty.io#489
The existing MP Rest Client guide ( https://openliberty.io/guides/microprofile-rest-client.html ) uses MP Rest Client 1.1 APIs, and with MP Rest Client 1.2 about to release, we should probably update the guide to take advantage of some of the new features in 1.2 - specifically:
@RegisterRestClient
annotation on the rest client interface@ClientHeaderParam
annotation to send hardcoded or computed HTTP headersMost of the other features in 1.2 are used for integration with other technologies like MP Open Tracing or MP Fault Tolerance. These features could be added in different guides that focus on these other technologies.
From https://bigblue.aha.io/features/ENGAGE-11
Today, when you need to figure out a server configuration, you look in our documentation, you look at the information for the particular configuration element, you try to understand what is described but you will have a hard time trying to piece together which attribute will work with which and how everything fits together for what you want to get done. Soon, you will scratch your heard, have to dig around even harder to no avail, and eventually, may have to resort to asking an exert i.e. calling IBM. This is undesirable for both OL and WL.
If we can provide sample configuration snippets that work, encapsulate best practices, put proper description and guidance, and make them easily accessible and available to developers and users, that will go a long way to make what we have much more consumable, enable users to get going much faster, and providing a pleasant if not improved user experience.
From https://github.ibm.com/was-liberty/liberty-docs/issues/807
Was put in KC here: https://www.ibm.com/support/knowledgecenter/en/SSEQTP_liberty/com.ibm.websphere.wlp.doc/ae/twlp_dev_ds_sharding.html
Also relevant is this blog post: https://openliberty.io/blog/2019/02/19/mongodb-with-open-liberty.html
Dev contacts: Fred Rowe and Mark Swatosh
Reviewed the MP Intro topic (https://openliberty.io/docs/intro/microprofile.html) with Dan Kehn. I applied some of the edits we documented here (in blue and marked 'Done' in red): https://ibm.box.com/s/eaeuvpt16u9n0suz79zrb0z31kxvk6k0
The remaining suggested edits should also be applied to improve the readability of the article (marked in red with 'TODO').
Write a simple common task of how to enable logging. Don't include loads of optional steps: just tell them how to do it to get it working. Then link to the relevant reference topics for other options, probably this one: https://openliberty.io/docs/ref/config/#logging.html
Provide examples for common scenarios as shown in https://www-03preprod.ibm.com/support/knowledgecenter/SSEQTP_liberty_temp/com.ibm.websphere.wlp.doc/ae/rwlp_logging.html
Sources of info
How to enable logging, see after the table in this topic:
https://www-03preprod.ibm.com/support/knowledgecenter/SSEQTP_liberty_temp/com.ibm.websphere.wlp.doc/ae/rwlp_logging.html
Enabling JSON logging:
https://www-03preprod.ibm.com/support/knowledgecenter/SSEQTP_liberty_temp/com.ibm.websphere.wlp.doc/ae/rwlp_http_accesslogs.html
We need an introduction to Open Liberty. (This is a test for training purposes.)
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google ❤️ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.